jira-mcp-server

robwilde/jira-mcp-server

3.2

If you are the rightful owner of jira-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Jira MCP Server provides seamless integration with Jira for the Claude Code CLI, enabling efficient issue management and user interaction.

Tools
4
Resources
0
Prompts
0

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 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 for detailed troubleshooting.

License

MIT

Contributing

Contributions welcome! Please submit issues or pull requests.

Support

  • Check for configuration help
  • Review 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