Jira MCP Server

A Jira MCP server that uses FastMCP 2.0's OpenAPI integration to expose Jira functionality through the Model Context Protocol (MCP).

Features

• OpenAPI integration - Generates MCP tools from Jira's API specification
• Secure authentication - Uses Jira API tokens
• Multiple transports - Support for stdio, HTTP, and SSE protocols
• Security filtering - Only exposes read-only endpoints by default
• Type-safe - Built with Python type hints and Pydantic models

Quick Start

1. Setup Jira API Token

1. Go to Atlassian Account Settings
2. Create an API token
3. Note your Jira instance URL (e.g., https://yourcompany.atlassian.net)

2. Configure Environment

# Copy and customize the environment file
cp .env .env.local
# Edit .env.local with your Jira credentials and preferred configuration

Required variables:

• JIRA_BASE_URL: Your Jira instance URL
• JIRA_API_USER: Your Jira username/email
• JIRA_API_TOKEN: Your API token
• MCP_ROUTE_CONFIG_PATH: Path to route configuration file
• MCP_ROUTE_CONFIG_NAME: Configuration name to use

3. Run with Docker (Recommended)

docker run -e JIRA_BASE_URL=https://yourcompany.atlassian.net \
           -e JIRA_API_USER=your-email@company.com \
           -e JIRA_API_TOKEN=your-api-token \
           ghcr.io/brukhabtu/jira-mcp:latest

How It Works

The server:

1. Downloads Jira's OpenAPI specification
2. Generates MCP tools for Jira API endpoints
3. Authenticates requests using your API token
4. Applies security filtering to expose only safe operations

Available functionality:

• Issue reading and search
• Project information
• User and team data
• Agile boards and sprints
• Dashboards and filters

Configuration

Environment Variables

Command Line Options

jira-mcp [OPTIONS]

Options:
  --transport {stdio,http,sse} Transport method (overrides MCP_TRANSPORT env var)
  --port PORT                  Port for HTTP/SSE transport (overrides MCP_PORT env var)
  --version                    Show version and exit
  --help                       Show help message

Integration with MCP Clients

Claude Desktop (Recommended)

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "jira": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env", "JIRA_BASE_URL=https://yourcompany.atlassian.net",
        "--env", "JIRA_API_USER=your-email@company.com", 
        "--env", "JIRA_API_TOKEN=your-api-token",
        "ghcr.io/brukhabtu/jira-mcp:latest"
      ]
    }
  }
}

For enhanced security, set credentials as environment variables in your shell profile:

export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export JIRA_API_USER="your-email@company.com"
export JIRA_API_TOKEN="your-api-token"

Then use:

{
  "mcpServers": {
    "jira": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env", "JIRA_BASE_URL",
        "--env", "JIRA_API_USER",
        "--env", "JIRA_API_TOKEN", 
        "ghcr.io/brukhabtu/jira-mcp:latest"
      ]
    }
  }
}

Development

# Install dependencies
uv sync

# Run tests
uv run pytest

# Type checking and linting
uv run mypy jira_mcp/
uv run ruff check .
uv run ruff format .

Architecture

• jira_mcp/config.py: Pydantic models with environment variable loading
• jira_mcp/auth.py: HTTP client with Jira Basic Auth
• jira_mcp/server.py: FastMCP integration with OpenAPI spec fetching
• jira_mcp/__main__.py: CLI interface with environment-based configuration

Troubleshooting

Common Issues

"Configuration error" on startup: Check that all required environment variables (JIRA_BASE_URL, JIRA_API_USER, JIRA_API_TOKEN) are set.

Authentication errors: Verify your API token is correct and your email matches your Jira account.

Connection timeout: Check your JIRA_BASE_URL is correct and accessible. Increase JIRA_TIMEOUT if needed.

Claude Desktop not finding server: Ensure environment variables are available to GUI applications (may require restart or launchctl setenv on macOS).

Getting Help

• Check the CLAUDE.md file for development guidance
• Review test files for usage examples
• Run jira-mcp --help for command line options

Security

Security Filtering

Default Security Model:

• Blocks all destructive operations (POST, PUT, PATCH, DELETE)
• Allows only safe read-only GET endpoints
• Default deny for everything else

Endpoints Exposed:

• Issue reading and search
• Project metadata
• User and team information
• Agile boards and sprint data
• Dashboards and saved filters
• System information and field metadata

Configuration:

# Default: Security filtering enabled
MCP_ENABLE_SECURITY_FILTERING=true

# Disable filtering (exposes all endpoints)
MCP_ENABLE_SECURITY_FILTERING=false  # Use with caution

Additional Security Measures

• API tokens are stored in environment variables, never in code or config files
• All HTTP requests use TLS encryption
• No sensitive data is logged or exposed
• Follows OAuth 2.0 and Atlassian security best practices

License

MIT