-
securityF
license-
qualityA server implementation that allows AI models to interact with Jira through the Model Context Protocol, enabling tasks like JQL searches and retrieving issue details.
Last updated -
Automatically exposes the entire Jira instance through MCP, providing access to issue management, project administration, user and permission management, dashboards, filters, webhooks, automation, and all other Jira Cloud API features with zero configuration overhead.
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
Create an API token
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 URLJIRA_API_USER: Your Jira username/emailJIRA_API_TOKEN: Your API tokenMCP_ROUTE_CONFIG_PATH: Path to route configuration fileMCP_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:
Downloads Jira's OpenAPI specification
Generates MCP tools for Jira API endpoints
Authenticates requests using your API token
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
Variable | Required | Default | Description |
| ✅ | - | Your Jira instance URL (e.g.,
) |
| ✅ | - | Your Jira username/email address |
| ✅ | - | Your Jira API token |
| ❌ |
| HTTP timeout in seconds |
| ❌ | bundled | Path to custom OpenAPI spec file |
| ❌ |
| Transport method (
,
,
) |
| ❌ |
| Port for HTTP/SSE transports |
| ❌ |
| Logging level (
,
,
,
) |
| ❌ |
| Enable security filtering (blocks destructive operations) |
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 loadingjira_mcp/auth.py: HTTP client with Jira Basic Authjira_mcp/server.py: FastMCP integration with OpenAPI spec fetchingjira_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 --helpfor 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
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A production-ready server that automatically exposes your entire Jira instance through the Model Context Protocol, allowing seamless interaction with Jira's API features including issue management, project administration, and user management.
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server that provides integration with Jira, allowing Large Language Models to interact with Jira projects, boards, sprints, and issues through natural language.Last updated -5202MIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that enables interaction with Jira's REST API using natural language commands, allowing users to manage Jira projects, issues, comments, and workflows through Claude Desktop and other MCP clients.Last updated -101MIT License
- -securityAlicense-qualityA Simple Model Context Protocol server that enables AI assistants to interact with Jira, allowing operations like fetching tickets, adding comments, and updating ticket status.Last updated -1Apache 2.0