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

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

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:

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:

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):

{
  "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.