Which integrations are available for this server?

Enables searching for issues using JQL queries, retrieving comprehensive issue details including subtasks, linked issues, comments, and metadata for project management and release planning.

JIRA MCP Server

A Model Context Protocol (MCP) server that enables Claude AI to interact with JIRA for project management, issue tracking, and release planning. This server provides seamless integration between Claude and your JIRA instance.

Features

MCP Tools

1. `search_jira_issues`

Search for JIRA issues using JQL (JIRA Query Language).

Parameters:

jql_query (str, required): JQL query string
max_results (int, optional): Maximum number of results (default: 100)
include_comments (bool, optional): Include issue comments (default: False)

Example:

search_jira_issues( jql_query="project = MYPROJECT AND status != Closed", max_results=50, include_comments=True )

2. `get_jira_issue_details` (Enhanced)

Get comprehensive details about a specific JIRA issue, including subtasks and linked issues.

Parameters:

issue_key (str, required): JIRA issue key (e.g., "PROJECT-123")
include_comments (bool, optional): Include comments (default: True)
include_subtasks (bool, optional): Include child issues/subtasks (default: True)
include_linked_issues (bool, optional): Include related issues with link types (default: True)

Returns:

{ "status": "success", "message": "Retrieved issue PROJECT-123", "issue": { "key": "PROJECT-123", "summary": "Implement New Feature", "description": "Add support for the new feature...", "status": "In Progress", "type": "Story", "priority": "High", "assignee": "John Doe", "reporter": "Jane Smith", "created": "2025-01-01T10:00:00.000+0000", "updated": "2025-01-15T15:30:00.000+0000", "fix_versions": ["Release 1.0", "Release 2.0"], "comments": [ { "author": "John Doe", "created": "2025-01-10T12:00:00.000+0000", "body": "Started implementation" } ], "subtasks": [ { "key": "PROJECT-124", "summary": "Design API", "status": "Done", "type": "Sub-task" }, { "key": "PROJECT-125", "summary": "Implement Parser", "status": "In Progress", "type": "Sub-task" } ], "linked_issues": [ { "link_type": "blocks", "key": "PROJECT-100", "summary": "Hardware Support", "status": "Open" }, { "link_type": "relates to", "key": "PROJECT-200", "summary": "Related Feature", "status": "In Progress" } ] } }

Example:

# Get full issue details with all relationships get_jira_issue_details("PROJECT-123") # Get issue without comments get_jira_issue_details("PROJECT-123", include_comments=False) # Get only basic issue info (no relations) get_jira_issue_details( "PROJECT-123", include_comments=False, include_subtasks=False, include_linked_issues=False )

Key Enhancements

🎯 Single API Call Efficiency

The enhanced get_jira_issue_details uses JIRA's expand parameters to fetch issue details, subtasks, and linked issues in a single API call, reducing latency and API usage.

🔗 Automatic Relationship Resolution

No need for separate JQL queries like:

❌ parent = PROJECT-123 (for subtasks)
❌ issue in linkedIssues(PROJECT-123) (for linked issues)

Everything is fetched automatically!

🎛️ Flexible Options

Choose exactly what data you need with granular control over comments, subtasks, and linked issues.

Installation

Prerequisites

Python 3.8+
JIRA API Bearer token

Setup

Clone or download the repository
Install dependencies:

pip install -r requirements.txt

Key dependencies:

fastmcp==0.4.1 - MCP server framework
mcp==1.5.0 - Model Context Protocol SDK
requests==2.32.3 - HTTP client for JIRA API

Set up environment variables:

Create a .env file or set environment variables:

export JIRA_SERVER_URL="https://your-jira-instance.atlassian.net" export JIRA_API_TOKEN="your_jira_bearer_token_here"

On Windows:

set JIRA_SERVER_URL=https://your-jira-instance.atlassian.net set JIRA_API_TOKEN=your_jira_bearer_token_here

Getting Your JIRA API Token

Log in to your JIRA instance
Navigate to Profile → Personal Access Tokens
Create a new token with appropriate permissions
Copy the token and store it securely

Required Permissions:

Read issues
Browse projects
View comments

Usage

Starting the MCP Server

python jira_mcp_tool.py

The server will start and listen for MCP protocol messages from Claude.

Using with Claude Desktop

Add to your Claude Desktop MCP configuration:

macOS/Linux: ~/.config/claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{ "mcpServers": { "jira": { "command": "python", "args": ["/path/to/jira_mcp_server.py"], "env": { "JIRA_SERVER_URL": "https://your-jira-instance.atlassian.net", "JIRA_API_TOKEN": "your_token_here" } } } }

Example Workflows

1. Finding and Analyzing Issues

User: "Find all high-priority bugs in my project that are still open" Claude uses: search_jira_issues( jql_query="project = MYPROJECT AND type = Bug AND priority = High AND status = Open" )

2. Getting Complete Issue Context

User: "Show me all details about PROJECT-123 including what it blocks and its subtasks" Claude uses: get_jira_issue_details("PROJECT-123") Result includes: - Issue details - All subtasks - All linked issues (blocks, is blocked by, relates to, etc.) - Comments

3. Release Planning Analysis

User: "Analyze the completion status of PROJECT-123 and its dependencies" Claude uses: 1. get_jira_issue_details("PROJECT-123") - gets issue with all relations 2. Analyzes subtasks completion 3. Checks linked issues status 4. Provides comprehensive report

Architecture

Component Overview

┌─────────────────────────────────────────────────┐ │ Claude AI Assistant │ └─────────────────┬───────────────────────────────┘ │ MCP Protocol ▼ ┌─────────────────────────────────────────────────┐ │ FastMCP Server Framework │ │ ┌───────────────────────────────────────────┐ │ │ │ @mcp.tool() │ │ │ │ - search_jira_issues() │ │ │ │ - get_jira_issue_details() │ │ │ └───────────────────────────────────────────┘ │ └─────────────────┬───────────────────────────────┘ │ HTTPS/Bearer Token ▼ ┌─────────────────────────────────────────────────┐ │ JIRA REST API v2 │ │ - /rest/api/2/search (JQL queries) │ │ - /rest/api/2/issue/{key}?expand=... │ │ - /rest/api/2/issue/{key}/comment │ └─────────────────────────────────────────────────┘

API Endpoints Used

Function	Endpoint	Method	Purpose
`search_jira_issues`	`/rest/api/2/search`	GET	JQL-based issue search
`get_issue_with_relations`	`/rest/api/2/issue/{key}?expand=subtasks,issuelinks`	GET	Single issue with relations
`get_issue_comments`	`/rest/api/2/issue/{key}/comment`	GET	Issue comments

Data Flow

get_jira_issue_details("PROJECT-123", include_subtasks=True, include_linked_issues=True) │ ├─→ get_issue_with_relations() │ │ │ └─→ GET /rest/api/2/issue/PROJECT-123?expand=subtasks,issuelinks │ │ │ └─→ Returns: issue + subtasks + linked issues │ ├─→ get_issue_comments() │ │ │ └─→ GET /rest/api/2/issue/PROJECT-123/comment │ │ │ └─→ Returns: comments list │ └─→ Combine data and return comprehensive response

Testing

Running Unit Tests

# Using pytest python -m pytest test_jira_mcp_tool.py -v # Using unittest python -m unittest test_jira_mcp_tool.py

Test Coverage

The test suite covers:

✅ Fetching issues with subtasks
✅ Fetching issues with linked issues
✅ Handling issues with no relations
✅ Optional parameter combinations
✅ Error handling (404, API errors, exceptions)
✅ Input validation
✅ Missing authentication token
✅ Backward compatibility

Manual Testing

Test the server with real JIRA issues:

# Start the server python jira_mcp_server.py # In Claude Desktop, try: # "Get details about PROJECT-123" # "Find all open bugs in project MYPROJECT"

Configuration

Environment Variables

Variable	Required	Description
`JIRA_SERVER_URL`	Yes	Your JIRA instance URL (e.g., `https://your-company.atlassian.net`)
`JIRA_API_TOKEN`	Yes	Bearer token for JIRA authentication

Development

Project Structure

. ├── jira_mcp_server.py # Main MCP server implementation ├── test_jira_mcp_tool.py # Unit tests ├── util.py # Utility functions ├── requirements.txt # Python dependencies ├── README.md # This file ├── LICENSE # MIT License └── .env # Environment variables (git-ignored)

Adding New Tools

To add a new MCP tool:

Define function with @mcp.tool() decorator:

@mcp.tool() def my_new_tool(param: str) -> Dict[str, Any]: """Tool description for Claude.""" # Implementation return {"status": "success", "data": ...}

Add tests in test_jira_mcp_tool.py
Update this README

Code Style

Type hints for all function parameters and returns
Comprehensive docstrings (Google style)
Error handling with try/except blocks
Null-safe field extraction from JIRA responses

Troubleshooting

Common Issues

Authentication Errors

Error: JIRA_API_TOKEN not found in environment variables

Solution: Set the JIRA_API_TOKEN environment variable.

Connection Errors

Error: JIRA API error: 401 - Unauthorized

Solution:

Check that your token is valid
Ensure the token has required permissions
Verify the token hasn't expired

Missing JIRA Server URL

Error: JIRA_SERVER_URL not found in environment variables

Solution: Set the JIRA_SERVER_URL environment variable to your JIRA instance URL.

404 Errors

Error: Issue PROJECT-123 not found

Solution:

Verify the issue key is correct
Check you have permission to view the issue
Ensure the issue exists in JIRA

Import Errors

ModuleNotFoundError: No module named 'fastmcp'

Solution: Install dependencies:

pip install -r requirements.txt

Debug Mode

To enable debug output, uncomment the print statement in jira_mcp_server.py:

if __name__ == "__main__": print("Starting JIRA MCP Server...") # Uncomment for debug mcp.run()

Security Considerations

Token Storage

✅ Store tokens in environment variables or secure secret management
❌ Never commit tokens to version control
❌ Never hardcode tokens in source files

API Permissions

Grant minimal required permissions:

Read issues
Browse projects
View comments

Avoid:

Admin permissions
Issue creation/modification (unless needed)
Project administration

Network Security

All API calls use HTTPS
Bearer token authentication
No credentials stored in code

Performance

API Call Optimization

The enhanced get_jira_issue_details reduces API calls:

Before:

1. GET /rest/api/2/search (get issue) 2. GET /rest/api/2/search?jql=parent=PROJECT-123 (get subtasks) 3. GET /rest/api/2/search?jql=issue in linkedIssues(...) (get links) 4. GET /rest/api/2/issue/{key}/comment (get comments) Total: 4 API calls

After:

1. GET /rest/api/2/issue/{key}?expand=subtasks,issuelinks (get all) 2. GET /rest/api/2/issue/{key}/comment (get comments) Total: 2 API calls (50% reduction)

Rate Limiting

JIRA Cloud typically limits:

~300 requests per minute per user
~100,000 requests per day per app

This server includes no built-in rate limiting. For high-volume usage, consider adding:

Request throttling
Response caching
Exponential backoff

Changelog

Version 2.0 (Current)

Enhanced get_jira_issue_details

✨ Added automatic subtask retrieval
✨ Added automatic linked issues retrieval
✨ Added optional parameters for granular control
⚡ Optimized to use single API call with expand parameters
📝 Comprehensive docstrings and type hints
✅ Full test coverage

Version 1.0

Initial Release

Basic search_jira_issues functionality
Basic get_jira_issue_details functionality
Bearer token authentication

Contributing

Guidelines

Code Quality
- Add type hints
- Write docstrings
- Follow existing patterns
Testing
- Add unit tests for new features
- Ensure all tests pass
- Maintain >80% coverage
Documentation
- Update README for new features
- Add inline comments for complex logic
- Include usage examples

Submitting Changes

Test your changes thoroughly
Update tests and documentation
Submit with clear description of changes

License

MIT License - see LICENSE file for details.

Support

For issues or questions:

Check the Troubleshooting section
Review JIRA REST API documentation
Check MCP protocol documentation at https://modelcontextprotocol.io

References

Enabling AI-powered JIRA analysis and project management