jiramcp by hlibkoval - MCP Server

JiraMCP

MCP server wrapping jira-cli for LLM integration

JiraMCP provides a comprehensive Model Context Protocol (MCP) server that wraps the excellent jira-cli tool, enabling AI assistants like Claude to interact with Jira seamlessly.

Features

Complete jira-cli Integration: Access all jira-cli functionality through MCP tools
Docker-based: Packaged as a Docker image for easy deployment
Full Configuration Support: Supports all jira-cli configuration options
Jira Server & Cloud: Works with both Jira Server/Data Center and Jira Cloud
Type-safe: Built with Python type hints and Pydantic validation
Comprehensive Tools: 30+ tools covering issues, epics, sprints, projects, and more

Quick Start

Prerequisites

Docker installed on your system
Jira server access with credentials
Claude Desktop (or another MCP-compatible client)

Installation

Pull the Docker image (once published):

docker pull ghcr.io/goroskob/jiramcp:latest

Or build locally:

git clone https://github.com/goroskob/jiramcp.git
cd jiramcp
docker build -t jiramcp:latest .

Configure Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "jiramcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env", "JIRA_SERVER",
        "--env", "JIRA_LOGIN",
        "--env", "JIRA_API_TOKEN",
        "--env", "JIRA_INSTALLATION=Local",
        "--env", "JIRA_AUTH_TYPE=basic",1
        "ghcr.io/goroskob/jiramcp:latest"
      ],
      "env": {
        "JIRA_SERVER": "https://jira.example.com",
        "JIRA_LOGIN": "your.email@example.com",
        "JIRA_API_TOKEN": "your-password-or-token"
      }
    }
  }
}

Restart Claude Desktop

Configuration

Required Environment Variables

Variable	Description	Example
`JIRA_SERVER`	Jira server URL	`https://jira.example.com`
`JIRA_LOGIN`	Username or email	`john.doe@example.com`
`JIRA_API_TOKEN`	Password or API token	`your-password-here`

Optional Environment Variables

Variable	Default	Description
`JIRA_INSTALLATION`	`Local`	`Local` for Server/DC, `Cloud` for Jira Cloud
`JIRA_AUTH_TYPE`	`basic`	Auth type: `basic`, `bearer`, or `mtls`
`JIRA_PROJECT_KEY`	-	Default project key (e.g., `PROJ`)
`JIRA_PROJECT_TYPE`	-	Project type: `scrum` or `kanban`
`JIRA_BOARD_NAME`	-	Default board name
`JIRA_FORCE_TTY`	`true`	Force TTY mode
`JIRA_DEBUG`	`false`	Enable debug logging
`JIRA_INSECURE`	`false`	Skip TLS verification (not recommended)
`OUTPUT_FORMAT`	`plain`	Output format: `plain`, `json`, or `pretty`
`ENABLED_SCOPES`	`all`	Tool scopes to enable (see below)

Installation Types

For Jira Server / Data Center:

"JIRA_INSTALLATION": "Local"

Uses /rest/api/2/ endpoints

For Jira Cloud:

"JIRA_INSTALLATION": "Cloud"

Uses /rest/api/3/ endpoints

Authentication Types

Basic Authentication (most common):

"JIRA_AUTH_TYPE": "basic",
"JIRA_API_TOKEN": "your-password"

Bearer Token (API tokens):

"JIRA_AUTH_TYPE": "bearer",
"JIRA_API_TOKEN": "your-api-token"

Mutual TLS (client certificates):

"JIRA_AUTH_TYPE": "mtls"

Output Format

JiraMCP supports three output formats controlled by the OUTPUT_FORMAT environment variable:

Available Formats:

plain (default) - Tab-delimited structured output, ideal for programmatic parsing
- Compact and efficient
- Easy to parse in scripts
- Recommended for AI assistants
json - JSON formatted output
- Fully structured data
- Best for integration with other tools
- Enables advanced data processing
pretty - Human-readable formatted output
- Colorized and formatted for terminal display
- Great for interactive debugging
- Most readable for humans

Examples:

# Use plain format (default)
OUTPUT_FORMAT=plain

# Use JSON format for structured data
OUTPUT_FORMAT=json

# Use pretty format for human readability
OUTPUT_FORMAT=pretty

In Claude Desktop config:

{
  "mcpServers": {
    "jiramcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", ...],
      "env": {
        "JIRA_SERVER": "https://jira.example.com",
        "JIRA_LOGIN": "user@example.com",
        "JIRA_API_TOKEN": "your-token",
        "OUTPUT_FORMAT": "plain"
      }
    }
  }
}

Tool Scopes

You can selectively enable tool categories using the ENABLED_SCOPES environment variable. This is useful when you only need specific functionality:

Available Scopes:

util - Utility tools (2 tools: jira_me, jira_serverinfo)
issue - Issue management tools (12 tools)
epic - Epic management tools (4 tools)
sprint - Sprint management tools (2 tools)
project - Project/board/release tools (4 tools)
all - Enable all scopes (default)

Examples:

# Enable all tools (default)
ENABLED_SCOPES=all

# Enable only issue and epic tools
ENABLED_SCOPES=issue,epic

# Enable only utility tools (useful for testing connectivity)
ENABLED_SCOPES=util

# Enable project and sprint management only
ENABLED_SCOPES=project,sprint

In Claude Desktop config:

{
  "mcpServers": {
    "jiramcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", ...],
      "env": {
        "JIRA_SERVER": "https://jira.example.com",
        "JIRA_LOGIN": "user@example.com",
        "JIRA_API_TOKEN": "your-token",
        "ENABLED_SCOPES": "issue,epic"
      }
    }
  }
}

Available Tools

Utility Tools

jira_me - Get current authenticated user
jira_serverinfo - Get server version and information

Issue Management

issue_list - List and search issues with advanced filtering
issue_view - View detailed issue information
issue_create - Create new issues
issue_edit - Edit existing issues
issue_assign - Assign issues to users
issue_move - Transition issue status
issue_delete - Delete issues
issue_link / issue_unlink - Link/unlink related issues
issue_clone - Clone/duplicate issues
issue_watch - Watch/unwatch issues
issue_comment_add - Add comments to issues

Epic Management

epic_list - List epics in a project
epic_create - Create new epics
epic_add - Add issues to epics
epic_remove - Remove issues from epics

Sprint Management

sprint_list - List sprints
sprint_add - Create new sprints

Project & Board Management

project_list - List all accessible projects
board_list - List boards in a project
release_list - List versions/releases
release_create - Create new versions

Usage Examples

Once configured, you can interact with Jira through Claude:

You: "List all high-priority bugs in project YSS"

You: "Create a new task in YSS with summary 'Fix login issue' assigned to john.doe"

You: "Show me details for issue YSS-123"

You: "Move YSS-123 to In Progress status"

You: "List all epics in the current sprint"

Advanced Filtering

JQL Support

Use the jql parameter in issue_list for complex queries:

# Issues updated in the last week
issue_list(jql="updated >= -7d AND status != Done")

# My open high-priority bugs
issue_list(jql="assignee = currentUser() AND type = Bug AND priority = High AND status != Done")

# Issues in epic
issue_list(jql="parent = YSS-100")

Date Filters

Multiple date format options:

Absolute: yyyy-mm-dd (e.g., 2025-01-15)
Relative: -10d (10 days ago)
Named: today, week, month, year

Status and Label Filtering

# Multiple statuses
issue_list(project="YSS", status=["Open", "In Progress", "Code Review"])

# Multiple labels
issue_list(project="YSS", labels=["backend", "urgent"])

Transport Options

JiraMCP supports multiple transport protocols for different use cases:

STDIO Transport (Default)

Used by Claude Desktop and other MCP clients:

docker run --rm -i \
  -e JIRA_SERVER=https://jira.example.com \
  -e JIRA_LOGIN=user@example.com \
  -e JIRA_API_TOKEN=your-token \
  jiramcp:latest

HTTP Transport (Streamable)

For web services and HTTP-based integrations:

docker run --rm -d \
  -p 8000:8000 \
  -e JIRA_SERVER=https://jira.example.com \
  -e JIRA_LOGIN=user@example.com \
  -e JIRA_API_TOKEN=your-token \
  jiramcp:latest \
  --transport http --host 0.0.0.0 --port 8000

Server will be available at http://localhost:8000/mcp

SSE Transport (Legacy)

For Server-Sent Events streaming:

docker run --rm -d \
  -p 8000:8000 \
  -e JIRA_SERVER=https://jira.example.com \
  -e JIRA_LOGIN=user@example.com \
  -e JIRA_API_TOKEN=your-token \
  jiramcp:latest \
  --transport sse --host 0.0.0.0 --port 8000

Testing with HTTP Transport

1. Initialize MCP Session

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
  }'

Response includes mcp-session-id header - save this for subsequent requests.

2. Send Initialized Notification

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

3. List Available Tools

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

4. Call Tools

Get current user:

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "jira_me",
      "arguments": {}
    }
  }'

View an issue:

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "issue_view",
      "arguments": {
        "issue_key": "PROJ-123",
        "comments": 5
      }
    }
  }'

List issues:

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "issue_list",
      "arguments": {
        "project": "PROJ",
        "status": ["Open", "In Progress"],
        "paginate": "0:10",
        "columns": "KEY,TYPE,STATUS,SUMMARY"
      }
    }
  }'

Using jq for Pretty Output

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' \
  2>/dev/null | grep '^data:' | cut -d' ' -f2- | jq '.result.tools[] | {name, description}' | head -50

Development

Local Development Setup

Clone the repository:

git clone https://github.com/goroskob/jiramcp.git
cd jiramcp

Create .env file:

cat > .env << EOF
JIRA_SERVER=https://jira.example.com
JIRA_LOGIN=your.email@example.com
JIRA_API_TOKEN=your-password-here
JIRA_INSTALLATION=Local
EOF

Build and run with docker-compose:

docker-compose up --build

Testing Read-Only Operations

For safe testing, use only read-only tools:

jira_me - Get current user
jira_serverinfo - Get server info
issue_view - View issue details
issue_list - List issues
epic_list - List epics
sprint_list - List sprints
project_list - List projects
board_list - List boards
release_list - List versions

Project Structure

jiramcp/
├── src/
│   └── jiramcp/
│       ├── __init__.py
│       ├── server.py          # Main FastMCP server
│       ├── config.py           # Configuration management
│       ├── cli_wrapper.py      # jira-cli command execution
│       └── tools/              # MCP tool implementations
│           ├── issues.py       # Issue management tools
│           ├── epics.py        # Epic tools
│           ├── sprints.py      # Sprint tools
│           ├── projects.py     # Project/board tools
│           └── utils.py        # Utility tools
├── tests/                      # Unit tests
├── Dockerfile                  # Docker image definition
├── docker-compose.yml          # Development setup
└── pyproject.toml             # Python package config

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=jiramcp --cov-report=html

Troubleshooting

Authentication Errors (403)

Problem: Authentication failed (403)

Solutions:

Verify credentials are correct
Check if CAPTCHA is required - solve it in your browser at your Jira URL
For Jira Cloud, ensure you're using an API token, not your password

Not Found Errors (404)

Problem: Resource not found (404)

Solutions:

Check JIRA_INSTALLATION setting:
- Use Local for Jira Server/Data Center
- Use Cloud for Jira Cloud
Verify the resource (issue, project, etc.) exists
Check you have permission to access the resource

Bad Request Errors (400)

Problem: Bad request (400)

Solutions:

Validate JQL syntax in Jira web UI first
Check field values are valid for your Jira instance
Ensure required fields are provided

Connection Issues

Problem: Cannot connect to Jira server

Solutions:

Verify JIRA_SERVER URL is correct and accessible
Check network connectivity
For self-signed certificates, set JIRA_INSECURE=true (not recommended for production)

Docker Issues

Problem: Docker container won't start

Solutions:

Check Docker is running: docker ps
View logs: docker logs <container-id>
Verify all required environment variables are set
Try running with --debug flag for detailed output

Security Notes

Never commit credentials: Use environment variables or secret management
API Token Security: Store tokens securely, rotate regularly
TLS Verification: Don't disable TLS verification (JIRA_INSECURE) in production
Container Security: Run container as non-root user (done by default)
Config Files: Config files are created with restrictive permissions (0600)

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request

License

MIT License - see LICENSE file for details

Acknowledgments

Built with FastMCP by Marvin
Wraps jira-cli by Ankit Pokhrel
Inspired by the Anthropic MCP ecosystem

Support

Report issues: https://github.com/goroskob/jiramcp/issues
Discussions: https://github.com/goroskob/jiramcp/discussions
jira-cli docs: https://github.com/ankitpokhrel/jira-cli#readme

hlibkoval/jiramcp

JiraMCP

Features

Quick Start

Prerequisites

Installation

Configuration

Required Environment Variables

Optional Environment Variables

Installation Types

Authentication Types

Output Format

Tool Scopes

Available Tools

Utility Tools

Issue Management

Epic Management

Sprint Management

Project & Board Management

Usage Examples

Advanced Filtering

JQL Support

Date Filters

Status and Label Filtering

Transport Options

STDIO Transport (Default)

HTTP Transport (Streamable)

SSE Transport (Legacy)

Testing with HTTP Transport

1. Initialize MCP Session

2. Send Initialized Notification

3. List Available Tools

4. Call Tools

Using jq for Pretty Output

Development

Local Development Setup

Testing Read-Only Operations

Project Structure

Running Tests

Troubleshooting

Authentication Errors (403)

Not Found Errors (404)

Bad Request Errors (400)

Connection Issues

Docker Issues

Security Notes

Contributing

License

Acknowledgments

Links

Support