Metadata-Version: 2.4
Name: workos-jira-mcp-server
Version: 1.0.1
Summary: MCP server for Jira project management — create issues, search with JQL, manage workflows, and track sprints.
Author: WorkOS Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/workos/workos-jira-mcp-server
Project-URL: Repository, https://github.com/workos/workos-jira-mcp-server
Project-URL: Issues, https://github.com/workos/workos-jira-mcp-server/issues
Keywords: mcp,jira,model-context-protocol,ai-tools,project-management
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Bug Tracking
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Dynamic: license-file

# Jira MCP Server

<!-- mcp-name: io.github.workos/jira-mcp-server -->

A production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for Jira project management. Connect any AI agent to Jira — create issues, search with JQL, manage workflows, track sprints, and more.

**This is an independent, generalized MCP server.** It is not tied to any specific project and can be connected to any AI agent that supports MCP (Claude Desktop, Cursor, WorkOS, or custom agents).

## Features

- 🎫 **Issues**: Create, read, update, search, and transition issues
- 🔍 **JQL Search**: Full Jira Query Language support
- 🔄 **Workflows**: Transition issues through statuses (To Do → In Progress → Done)
- 💬 **Comments**: Add comments to issues
- 📋 **Projects**: List accessible projects
- 🏃 **Sprints**: List sprints and get board details

## Installation

**Recommended — no pre-install required (uses [uv](https://docs.astral.sh/uv/)):**
```bash
# uv manages a temporary isolated environment automatically
uvx --from workos-jira-mcp-server jira-mcp-server
```

**Or install permanently with pip:**
```bash
pip install workos-jira-mcp-server
```

**Or install from source:**
```bash
git clone https://github.com/workos/workos-jira-mcp-server
cd workos-jira-mcp-server
pip install -e .
```

## Quick Start

```bash
export JIRA_BASE_URL="https://your-org.atlassian.net"
export JIRA_EMAIL="you@company.com"
export JIRA_API_TOKEN="your-api-token"

# Recommended: run via uvx (no install needed)
uvx --from workos-jira-mcp-server jira-mcp-server

# Or if installed via pip
jira-mcp-server

# Or run as a Python module
python -m jira_mcp_server
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `JIRA_BASE_URL` | ✅ Yes | Jira instance URL (e.g., `https://your-org.atlassian.net`) |
| `JIRA_EMAIL` | ✅ Yes | Email for Jira authentication |
| `JIRA_API_TOKEN` | ✅ Yes | API token ([generate here](https://id.atlassian.net/manage-profile/security/api-tokens)) |

### Getting a Jira API Token

1. Go to [Atlassian API Tokens](https://id.atlassian.net/manage-profile/security/api-tokens)
2. Click **Create API token**
3. Give it a label and click **Create**
4. Copy the token

## Connecting to AI Agents

> **Note:** Use `uvx --from workos-jira-mcp-server jira-mcp-server` in all configs below. The `--from` flag is needed because the PyPI package name (`workos-jira-mcp-server`) differs from the CLI entry point (`jira-mcp-server`). You must have [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (`brew install uv` on macOS).

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "jira": {
      "command": "uvx",
      "args": ["--from", "workos-jira-mcp-server", "jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_EMAIL": "you@company.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

> **Alternative** — if you have installed via `pip install workos-jira-mcp-server` and prefer not to use uvx, use the full absolute path to the binary instead:
> ```json
> { "command": "/path/to/your/bin/jira-mcp-server" }
> ```
> Find the path with: `which jira-mcp-server`

### Cursor

Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):

```json
{
  "mcpServers": {
    "jira": {
      "command": "uvx",
      "args": ["--from", "workos-jira-mcp-server", "jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_EMAIL": "you@company.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

### VS Code (GitHub Copilot / MCP extension)

Edit `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "jira": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "workos-jira-mcp-server", "jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "${input:jiraBaseUrl}",
        "JIRA_EMAIL": "${input:jiraEmail}",
        "JIRA_API_TOKEN": "${input:jiraToken}"
      }
    }
  },
  "inputs": [
    {
      "id": "jiraBaseUrl",
      "type": "promptString",
      "description": "Jira Site URL (e.g., https://your-org.atlassian.net)"
    },
    {
      "id": "jiraEmail",
      "type": "promptString",
      "description": "Jira account email"
    },
    {
      "id": "jiraToken",
      "type": "promptString",
      "description": "Jira API Token",
      "password": true
    }
  ]
}
```

### WorkOS / Custom Agents

Add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "jira": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["--from", "workos-jira-mcp-server", "jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "${JIRA_BASE_URL}",
        "JIRA_EMAIL": "${JIRA_EMAIL}",
        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
      }
    }
  }
}
```

## Available Tools (9)

| Tool | Description |
|------|-------------|
| `jira_get_issue` | Get a Jira issue by key |
| `jira_create_issue` | Create a new issue |
| `jira_update_issue` | Update fields on an existing issue |
| `jira_search_issues` | Search issues using JQL |
| `jira_transition_issue` | Transition an issue to a new status |
| `jira_add_comment` | Add a comment to an issue |
| `jira_list_projects` | List all accessible projects |
| `jira_list_sprints` | List sprints for a board |
| `jira_get_board` | Get board details |

## Development

```bash
git clone https://github.com/workos/workos-jira-mcp-server
cd workos-jira-mcp-server
pip install -e .

# Run tests
pytest

# Run the server locally
JIRA_BASE_URL=https://test.atlassian.net JIRA_EMAIL=test@co.com JIRA_API_TOKEN=test python -m jira_mcp_server
```

## Publishing

### To PyPI
```bash
pip install build twine
rm -rf dist/ build/ src/*.egg-info
python -m build
pip install "packaging>=24.2"   # required for Metadata 2.4 support in twine
twine check dist/*              # validate before uploading
twine upload dist/*
```

### To MCP Registry
```bash
mcp-publisher login github
mcp-publisher publish
```

## License

MIT — see [LICENSE](LICENSE) for details.
