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

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

Tool	Description
jira_search	Search issues using JQL with pagination
jira_get_issue	Get detailed issue information
jira_create_issue	Create new issues with custom fields and parent links
jira_update_issue	Update existing issue fields
jira_add_comment	Add comments to issues
jira_transition_issue	Change issue status
jira_list_projects	List accessible projects

Advanced Tools

Tool	Description
jira_link_issues	Create relationships between issues (Relates, Blocks, etc.)
jira_get_epic_issues	Get all issues belonging to an epic
jira_get_transitions	Get available transitions for an issue
jira_search_users	Search users by name or email
jira_assign_issue	Assign or unassign issues to users

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.