# Jira MCP Server (free-tier friendly)

A small MCP server that lets an MCP client (Claude Desktop, or any MCP client)
read, create, update, comment on, and transition Jira issues. Built and tested
against Jira Cloud's **free plan** — no paid Jira subscription needed.

## Tools it exposes

| Tool | What it does |
|---|---|
| `get_issue(issue_key)` | Fetch summary, description, status, assignee, etc. |
| `search_issues(jql, max_results)` | Run a JQL search |
| `create_issue(project_key, summary, description, issue_type)` | Create a new issue |
| `update_issue(issue_key, summary, description)` | Edit summary/description |
| `list_transitions(issue_key)` | See what statuses an issue can move to |
| `transition_issue(issue_key, status_name)` | Move an issue to a new status |
| `add_comment(issue_key, comment)` | Comment on an issue |

## 1. Get a free Jira Cloud site

1. Go to https://www.atlassian.com/software/jira and sign up (free, up to 10 users, unlimited projects).
2. Create a project and note its **project key** (e.g. `PROJ`) — shown next to the project name.
3. Create an API token at https://id.atlassian.com/manage-profile/security/api-tokens.

## 2. Install dependencies

```bash
cd jira-mcp-server
python3 -m venv venv
source venv/bin/activate        # on Windows: venv\Scripts\activate
pip install -r requirements.txt
```

## 3. Configure credentials

Copy `.env.example` to `.env` and fill in your values, **or** just export them
in your shell:

```bash
export JIRA_BASE_URL=https://yourcompany.atlassian.net
export JIRA_EMAIL=you@example.com
export JIRA_API_TOKEN=your-api-token-here
```

## 4. Test it directly (no Claude Desktop needed)

Edit `PROJECT_KEY` / `ISSUE_KEY` at the top of `test_client.py` to match your
Jira project, then:

```bash
python test_client.py
```

This spins up `jira_server.py` as a subprocess over stdio (the same way a
real MCP client would), lists the available tools, and exercises
`get_issue`, `search_issues`, and `create_issue` against your live Jira site.

## 5. Wire it into Claude Desktop (optional)

Add this to your Claude Desktop MCP config
(`claude_desktop_config.json` — Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "jira": {
      "command": "/absolute/path/to/jira-mcp-server/venv/bin/python",
      "args": ["/absolute/path/to/jira-mcp-server/jira_server.py"],
      "env": {
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_EMAIL": "you@example.com",
        "JIRA_API_TOKEN": "your-api-token-here"
      }
    }
  }
}
```

Restart Claude Desktop and ask it something like "what's the status of
PROJ-1?" — it should call the `get_issue` tool.

## Notes / gotchas

- Jira's v3 API stores descriptions and comments in **Atlassian Document
  Format** (ADF), not plain text. The server handles the conversion for you
  in both directions.
- `create_issue`'s `issue_type` must exactly match a type configured on that
  project (commonly `Task`, `Bug`, `Story`, `Epic`) — check your project's
  issue types if you get a "issuetype" error.
- The free plan caps you at 100 automation runs/month and 2 GB storage —
  irrelevant for this kind of manual/API testing, but worth knowing.
- This server uses **stdio transport**, meaning it only runs locally,
  launched by whatever MCP client talks to it — it isn't a public web
  service, which is the simplest and most common way to test MCP.