Jira Model Context Protocol (MCP) Server

A zero-dependency Model Context Protocol (MCP) server providing rich two-way integration with Jira Cloud and Jira Data Center / Server.

Designed for Google Antigravity, Cursor, Claude Desktop, Windsurf, and any MCP-compatible AI assistant or agent.

🚀 Features

• 🔍 Retrieve My Tickets (get_my_jira_tickets): Automatically queries Jira for assigned, reported, or mentioned tickets with status filters (open, in_progress, completed, all) and project filters.

• 📄 Inspect Issue Details (get_jira_ticket): View summary, status, priority, issue type, assignee, reporter, subtasks, attachments, comments, and description (with ADF to Markdown conversion).

• ✅ Complete Tickets (complete_jira_ticket): Smart transition resolver that discovers the workflow's target "Done" / "Resolved" transition and executes it with optional resolution notes.

• ✏️ Edit Issue Fields (update_jira_ticket): Update issue summaries, descriptions, priority, labels, or assignee.

• 🔄 Workflow Transitions (list_ticket_transitions & transition_jira_ticket): Inspect all available transitions for an issue and move it through any custom workflow state.

• 💬 Add Comments (add_jira_comment): Post internal notes or user-facing comments directly to issues.

• 🔎 JQL Search (search_jira_tickets): Run custom, complex Jira Query Language (JQL) expressions with custom field selection and pagination.

• 👤 User Profile & Diagnostics (get_jira_user_info): Inspect the currently authenticated Jira account and permissions.

• ⚡ Zero External Dependencies: Built entirely using Python's standard library (urllib, json, ssl).

Related MCP server: Jira MCP Server

🛠️ Available MCP Tools

⚙️ Quickstart & Installation

Prerequisites

• Python 3.8 or higher.

• A Jira Cloud or Jira Data Center / Server instance.

• An Atlassian API Token (for Jira Cloud).

1. Clone the Repository

git clone https://github.com/your-username/jira-mcp-server.git
cd jira-mcp-server

2. Configure Credentials

Create a .env file from the provided example:

cp .env.example .env

Edit .env with your Jira credentials:

JIRA_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your_api_token_here
JIRA_DEFAULT_USER=

How to generate an Atlassian API Token:

1. Log in to https://id.atlassian.com/manage-profile/security/api-tokens.

2. Click Create API token.

3. Give it a label (e.g., jira-mcp) and copy the generated token.

3. Test Connection

Verify your configuration and test authentication:

python3 setup_config.py --test

Or configure directly via CLI flags:

python3 setup_config.py --url https://your-domain.atlassian.net --email your-email@example.com --token YOUR_API_TOKEN --test

🔌 Connecting to AI Clients

1. Google Antigravity / Gemini CLI (mcp_config.json)

Add to ~/.gemini/config/mcp_config.json (or mcp_servers block):

{
  "mcpServers": {
    "jira": {
      "command": "python3",
      "args": ["/path/to/jira-mcp-server/server.py"],
      "env": {
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

2. Claude Desktop (claude_desktop_config.json)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "jira": {
      "command": "python3",
      "args": ["/path/to/jira-mcp-server/server.py"],
      "env": {
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

3. Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "jira": {
      "command": "python3",
      "args": ["/path/to/jira-mcp-server/server.py"],
      "env": {
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

🧪 Testing

Run the included unit test suite:

python3 test_server.py

🔒 Security & Privacy

• No telemetry or data logging: All communication occurs directly between your local machine and your Jira instance via standard HTTPS.

• Credential Storage: Credentials can be passed via environment variables, a local .env file, or standard MCP client configuration. The .env file is ignored by git by default.

📄 License

This project is licensed under the MIT License.