jira-mcp-server

Jira MCP Server

For Claude Code CLI

A Model Context Protocol (MCP) server that provides seamless Jira integration for Claude Code CLI.

Features

• Get Issue Details - Fetch complete information about any Jira issue
• Search Issues - Query issues using JQL (Jira Query Language)
• Get Comments - Retrieve all comments on an issue
• User Info - Get authenticated user details
• Multi-Environment Support - Connect to multiple Jira instances simultaneously
• Project-Specific Configuration - Different Jira environments per project via .mcp.json

Quick Start

1. Install

cd /var/home/mrwilde/mcp/jira-mcp-server
./install.sh

2. Configure (Per-Project)

Create .mcp.json in your project root:

cd /path/to/your/project

cat > .mcp.json <<'EOF'
{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["-m", "jira_mcp.server"],
      "env": {
        "JIRA_HOST": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DEFAULT_PROJECT": "PROJ"
      }
    }
  }
}
EOF

# Don't commit tokens!
echo ".mcp.json" >> .gitignore

3. Verify

claude mcp list

4. Use

In Claude Code CLI, simply ask:

• "Get details for issue LXP-449"
• "Search for all my open tasks"
• "Show comments on PROJ-123"

Installation & Configuration

See INSTALLATION.md for complete setup instructions including:

• System-wide installation
• Per-project configuration (.mcp.json)
• Global user configuration
• Multiple Jira environments
• CLI commands (claude mcp add)
• Security best practices

Configuration Methods

Method 1: Project .mcp.json File (Recommended)

{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["-m", "jira_mcp.server"],
      "env": {
        "JIRA_HOST": "https://company.atlassian.net",
        "JIRA_EMAIL": "you@company.com",
        "JIRA_API_TOKEN": "your-token"
      }
    }
  }
}

Method 2: Claude Code CLI Command

# Add to current project
cd /path/to/project
claude mcp add --scope project jira \
  --env JIRA_HOST=https://company.atlassian.net \
  --env JIRA_EMAIL=you@company.com \
  --env JIRA_API_TOKEN=your-token \
  -- python -m jira_mcp.server

# Add globally for all projects
claude mcp add --scope user jira \
  --env JIRA_HOST=https://company.atlassian.net \
  --env JIRA_EMAIL=you@company.com \
  --env JIRA_API_TOKEN=your-token \
  -- python -m jira_mcp.server

Development

Testing

# Test connection and authentication
source venv/bin/activate
python tests/test_connection.py

# Test with specific issue
python tests/test_connection.py LXP-449

Project Structure

jira-mcp-server/
├── src/jira_mcp/
│   ├── server.py       # MCP server implementation
│   └── jira_client.py  # Jira API wrapper
├── tests/
│   └── test_connection.py
├── config-examples/    # Configuration templates
│   ├── project-mcp.json
│   └── multi-environment-mcp.json
├── pyproject.toml
├── requirements.txt
├── install.sh          # Quick install script
└── INSTALLATION.md     # Complete setup guide

MCP Tools

get_issue

Fetch detailed information about a Jira issue.

Input: issue_key (string) - e.g., "LXP-449"

Returns: Full issue details including summary, description, status, assignee, priority, dates, and project info.

search_issues

Search for issues using JQL (Jira Query Language).

Input:

• jql (string) - Query string, e.g., "project = LXP AND status = 'To Do'"
• max_results (number, optional) - Default: 50

Returns: List of matching issues with key details.

get_issue_comments

Get all comments on a specific issue.

Input: issue_key (string)

Returns: List of comments with author, body, and timestamps.

get_current_user

Get information about the authenticated user.

Input: None

Returns: User details including username, email, and display name.

JQL Query Examples

# All issues in a project
project = LXP

# Your open issues
assignee = currentUser() AND status != Done

# Recent updates
updated >= -7d ORDER BY updated DESC

# Complex query
project = LXP AND status = "In Progress" AND assignee = currentUser()

Multiple Environments Example

{
  "mcpServers": {
    "jira-prod": {
      "command": "python",
      "args": ["-m", "jira_mcp.server"],
      "env": {
        "JIRA_HOST": "https://prod.atlassian.net",
        "JIRA_EMAIL": "you@company.com",
        "JIRA_API_TOKEN": "prod-token",
        "JIRA_DEFAULT_PROJECT": "LXP"
      }
    },
    "jira-staging": {
      "command": "python",
      "args": ["-m", "jira_mcp.server"],
      "env": {
        "JIRA_HOST": "https://staging.atlassian.net",
        "JIRA_EMAIL": "you@company.com",
        "JIRA_API_TOKEN": "staging-token",
        "JIRA_DEFAULT_PROJECT": "LXL"
      }
    }
  }
}

Claude Code CLI Commands

# List MCP servers
claude mcp list

# Get server details
claude mcp get jira

# Remove server
claude mcp remove --scope project jira

# Debug MCP issues
claude --mcp-debug

Getting a Jira API Token

1. Visit: https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Name it (e.g., "MCP Server - Project X")
4. Copy the token immediately
5. Add it to your .mcp.json

Security

• Never commit tokens to version control
• Add .mcp.json to .gitignore in every project
• Use project-specific tokens with minimal permissions
• Rotate tokens regularly (every 90 days)
• Revoke unused tokens
• Create .mcp.json.example templates for team onboarding

Requirements

• Python >= 3.10
• Claude Code CLI
• Jira Cloud account with API access
• API token for authentication

Dependencies

• mcp >= 1.0.0 - Model Context Protocol SDK
• jira >= 3.5.0 - Python Jira library
• python-dotenv >= 1.0.0 - Environment variable management
• httpx >= 0.27.0 - HTTP client

Troubleshooting

Module Not Found

Use full Python path in .mcp.json:

{
  "mcpServers": {
    "jira": {
      "command": "/var/home/mrwilde/mcp/jira-mcp-server/venv/bin/python",
      "args": ["-m", "jira_mcp.server"],
      ...
    }
  }
}

Check MCP Status

claude mcp list
claude --mcp-debug

See INSTALLATION.md for detailed troubleshooting.

License

MIT

Contributing

Contributions welcome! Please submit issues or pull requests.

Support

• Check INSTALLATION.md for configuration help
• Review CLAUDE.md for development guidance
• Open an issue on GitHub

Changelog

0.1.0 (2025-10-28)

• Initial release for Claude Code CLI
• Core MCP server implementation
• Four essential Jira tools (get_issue, search_issues, get_issue_comments, get_current_user)
• Multi-environment support via .mcp.json
• Project-specific configuration
• Comprehensive documentation