Jira MCP Server

A clean, reliable Model Context Protocol server for Jira integration, designed for use with Claude Desktop and other MCP clients.

Why This Exists

The existing Jira MCP servers have quality issues:

• Pydantic dependency conflicts

• Deprecated API usage (v2 instead of v3)

• Poor error handling

• Unreliable connections

This implementation focuses on:

• ✅ Modern Jira REST API v3

• ✅ Minimal, stable dependencies

• ✅ Proper error handling

• ✅ Multi-instance support

• ✅ Type safety throughout

Related MCP server: Jira MCP Server

Features

Core Operations

• 🔍 Search issues with JQL (Jira Query Language)

• 📄 Get issue details with full field information

• ➕ Create issues with descriptions, labels, parent/epic links, and custom fields

• ✏️ Update issues (summary, description, labels, etc.)

• 💬 Add comments to issues

• 🔄 Transition issues between statuses

• 📋 List projects accessible to the user

Advanced Features

• 🔗 Link issues with relationships (Relates, Blocks, Duplicates, etc.)

• 📊 Epic management - Create tasks under epics and query epic children

• 🔄 Get available transitions before transitioning issues

• 👥 User management - Search users and assign issues

• 🎯 Assignee control - Assign or unassign issues to team members

Multi-Instance Support

Connect to multiple Jira instances simultaneously:

• Different organizations

• Personal and work accounts

• Multiple teams

Quick Start

1. Installation

Option A: Install from PyPI (Recommended)

pip install jira-mcp-simple

Note: If jira-mcp command is not found, add Python's bin to PATH:

export PATH="$HOME/.local/bin:$PATH"

Option B: Install from source

git clone https://github.com/Positronic-AI/jira-mcp.git
cd jira-mcp
pip install -e .

2. Get Your Jira API Token

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

2. Click "Create API token"

3. Give it a name (e.g., "Claude Desktop MCP")

4. Copy the token

3. Test Connection

export JIRA_MYCOMPANY_URL="https://your-company.atlassian.net"
export JIRA_MYCOMPANY_EMAIL="your.email@company.com"
export JIRA_MYCOMPANY_TOKEN="your_api_token_here"

jira-mcp --test-connection mycompany

You should see:

✓ Connected successfully!
  User: Your Name (your@email.com)
  Account ID: 123abc...
  Accessible projects: N

4. Configure Claude Desktop

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp",
      "args": ["--instance", "mycompany"],
      "env": {
        "JIRA_MYCOMPANY_URL": "https://your-company.atlassian.net",
        "JIRA_MYCOMPANY_EMAIL": "your.email@company.com",
        "JIRA_MYCOMPANY_TOKEN": "your_api_token_here"
      }
    }
  }
}

Note: If you installed in a virtual environment, use the full path to jira-mcp, e.g., /path/to/venv/bin/jira-mcp

5. Restart Claude Desktop

Completely quit and reopen Claude Desktop.

6. Test It!

Try these commands in Claude:

List my Jira projects

Search for issues assigned to me

Show me PROJECT-123

Create a new task in PROJECT called "Test MCP integration"

Usage Examples

Natural Language Commands

Once configured, you can use natural language with Claude:

Basic Operations:

• "Find all open bugs in the MOBILE project"

• "Show me high priority issues assigned to me"

• "Create a task about fixing the login page"

• "Add a comment to PROJ-42 saying the fix is deployed"

• "Move PROJ-42 to In Progress"

• "Update the summary of PROJ-42 to include more details"

Advanced Operations:

• "Create a new epic called 'User Authentication System'"

• "Create a task under epic PROJ-10 for implementing login"

• "Link PROJ-42 to PROJ-50 with 'Blocks' relationship"

• "Show me all tasks under epic PROJ-10"

• "What transitions are available for PROJ-42?"

• "Search for user john.doe and assign PROJ-42 to them"

• "Unassign PROJ-42"

Direct JQL Queries

Search Jira with: project = PROJ AND status = "In Progress" ORDER BY priority DESC

Multi-Instance Configuration

To connect multiple Jira instances:

{
  "mcpServers": {
    "jira-work": {
      "command": "jira-mcp",
      "args": ["--instance", "work"],
      "env": {
        "JIRA_WORK_URL": "https://company.atlassian.net",
        "JIRA_WORK_EMAIL": "you@company.com",
        "JIRA_WORK_TOKEN": "token1"
      }
    },
    "jira-personal": {
      "command": "jira-mcp",
      "args": ["--instance", "personal"],
      "env": {
        "JIRA_PERSONAL_URL": "https://personal.atlassian.net",
        "JIRA_PERSONAL_EMAIL": "you@personal.com",
        "JIRA_PERSONAL_TOKEN": "token2"
      }
    }
  }
}

Claude will know which instance to use based on context.

Architecture

jira-mcp/
├── server.py          # Main MCP server
├── jira_client.py     # Jira REST API v3 wrapper
├── config.py          # Configuration management
├── requirements.txt   # Python dependencies
└── examples/          # Configuration examples

Key Design Decisions

Minimal Dependencies: Only essential, stable packages (mcp, httpx, pydantic, python-dotenv)

Modern API: Uses Jira REST API v3 (/rest/api/3/search/jql) instead of deprecated v2

Type Safety: Full type hints throughout for better IDE support and fewer bugs

Error Handling: Clear error messages propagated from Jira API

Multi-Instance: Environment-based configuration for multiple Jira instances

Available Tools

The server exposes these MCP tools:

Core Tools

Advanced Tools

Troubleshooting

Connection fails

• Verify your API token is correct

• Check the Jira URL has no trailing slash

• Ensure your email matches the Atlassian account

• Test with: jira-mcp --test-connection <instance>

Claude Desktop doesn't see the server

• Verify JSON config is valid

• Use absolute paths (not ~/ or relative)

• Restart Claude Desktop completely

• Check Claude Desktop logs for errors

"Module not found" errors

• Ensure jira-mcp-simple is installed: pip install jira-mcp-simple

• If using a virtual environment, ensure it's activated or use the full path

"Field cannot be set" errors

• Not all fields are available on all projects

• Check your project's issue type screen configuration

• Common issue: priority field not on screen (make it optional)

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Areas we'd especially appreciate help:

• Unit and integration tests

• Jira Data Center support

• Attachment handling

• Sprint/board operations

• Custom field improvements

Development

# Clone and setup
git clone https://github.com/Positronic-AI/jira-mcp.git
cd jira-mcp
pip install -e ".[dev]"

# Test connection
export JIRA_TEST_URL="https://test.atlassian.net"
export JIRA_TEST_EMAIL="test@example.com"
export JIRA_TEST_TOKEN="test_token"
jira-mcp --test-connection test

License

MIT License - see LICENSE for details.

Acknowledgments

• Built for use with Claude Desktop

• Uses the Model Context Protocol

• Inspired by the need for reliable Jira automation

Support

• 🐛 Report bugs

• 💡 Request features

• 📖 Documentation

• 💬 Discussions

Note: This is an independent project and is not affiliated with Atlassian or Anthropic.