atlassian-jira-mcp-server 1.0.0

Jira MCP (Model Context Protocol) server built with FastMCP for Jira Cloud API v3

Jira MCP Server

A comprehensive MCP (Model Context Protocol) server for Jira Cloud integration, built with FastMCP. This server provides a clean, well-structured interface to Jira's API with automatic ADF (Atlassian Document Format) handling for rich text formatting.

Features

• 5 Core Tools for complete Jira interaction
• 9 Resource endpoints for quick data access
• Automatic ADF formatting for descriptions and comments
• Email to Account ID resolution for user assignments
• JQL support for powerful search capabilities
• Automatic transition detection when fetching issues
• Jira Cloud API v3 compatibility
• Basic Authentication with API tokens

Installation

Prerequisites

• Python 3.10+
• Jira Cloud account
• Jira API token (create one here)
• uv (recommended) or pip

Installation Methods

Method 1: UV Tool Installation (Recommended for MCP usage)

This method installs the server as a standalone tool, ideal for use with Claude Desktop or other MCP clients.

# Install directly from source
uv tool install . --force --reinstall

# Or clone first, then install
git clone https://github.com/your-username/atlassian-jira-mcp-server
cd atlassian-jira-mcp-server
uv tool install . --force --reinstall

Test the installation:

# Should show environment variable requirements
atlassian-jira-mcp-server

Method 2: Virtual Environment Installation (Development)

For development or when you need to run the server directly:

git clone https://github.com/your-username/atlassian-jira-mcp-server
cd atlassian-jira-mcp-server

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .

Method 3: Direct pip Installation

Note: If you get "externally managed environment" errors, use Method 1 or 2 instead.

pip install -e .

Environment Configuration

1. Create environment file:

   cp .env.example .env
   

2. Edit .env with your Jira credentials:

   JIRA_BASE_URL=https://your-domain.atlassian.net
   JIRA_USERNAME=[e-mail]
   JIRA_API_TOKEN=your-api-token
   JIRA_DEFAULT_PROJECT=PROJ  # Optional
   

3. Test configuration:

   # With virtual environment
   source .venv/bin/activate
   python test_server.py
   
   # With uv tool installation
   JIRA_BASE_URL=https://your-domain.atlassian.net \
   JIRA_USERNAME=[e-mail] \
   JIRA_API_TOKEN=your-api-token \
   atlassian-jira-mcp-server
   

Usage

Running the Server

With UV Tool Installation

atlassian-jira-mcp-server

With Virtual Environment

source .venv/bin/activate
python server.py
# or
atlassian-jira-mcp-server

Development Workflow

After making code changes:

# Reinstall with uv tool
uv tool uninstall atlassian-jira-mcp-server && uv tool install . --reinstall

# Or with virtual environment
source .venv/bin/activate
pip install -e .

Connecting with Claude Desktop

Option 1: Install as Package (Recommended)

First, install the server:

pip install atlassian-jira-mcp-server
# or for development:
pip install -e /path/to/atlassian-jira-mcp-server

Then add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "jira": {
      "command": "atlassian-jira-mcp-server",
      "args": [],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "${JIRA_EMAIL}",
        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}",
        "JIRA_DEFAULT_PROJECT": "PROJ"
      }
    }
  }
}

You can use environment variable substitution with ${VAR_NAME} to reference system environment variables.

Option 2: Run Directly with Python

{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["/path/to/atlassian-jira-mcp-server/server.py"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "[e-mail]",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DEFAULT_PROJECT": "PROJ"
      }
    }
  }
}

Available Tools (5 Active)

Core Tools

1. get_issue - Get complete issue details with transitions included

   get_issue(issue_key="PROJ-123")
   # Returns LLM-optimized format with 'content' (text) and 'data' (structured)
   

2. search_issues - Search with JQL

   search_issues(jql="project = PROJ AND status = 'In Progress'", max_results=50)
   # Returns formatted results with both text summary and structured data
   

3. create_issue - Create new issue with rich formatting

   create_issue(
       project_key="PROJ",
       issue_type="Story",
       summary="Implement feature",
       description="## Overview\nDetailed description with **markdown** support"
   )
   

4. get_project - Get project configuration

   get_project(project_key="PROJ")
   # Returns project details, issue types, and workflows
   

5. update_issue - Unified tool for all issue modifications

   # Update fields
   update_issue(issue_key="PROJ-123", priority="High", labels=["backend"])
   
   # Transition status
   update_issue(issue_key="PROJ-123", transition="Done", resolution="Fixed")
   
   # Add comment
   update_issue(issue_key="PROJ-123", comment="Review complete")
   
   # Assign issue
   update_issue(issue_key="PROJ-123", assignee="[e-mail]")
   
   # Delete issue
   update_issue(issue_key="PROJ-123", delete=True)
   
   # Combined operations
   update_issue(
       issue_key="PROJ-123",
       transition="In Progress",
       assignee="[e-mail]",
       comment="Starting work on this"
   )
   

Resource Endpoints (9 Resources)

Access common data quickly through resource URIs:

• jira://active-users - Active Atlassian users for assignment/mentions
• jira://current-user/info - Current user details
• jira://my-issues - Your assigned issues
• jira://recent-issues - Recently updated issues
• jira://projects/list - All projects
• jira://metadata/issue-types - Issue type schemas
• jira://metadata/priorities - Priority levels
• jira://metadata/statuses - Status information
• jira://adf-examples - ADF formatting guide

ADF (Atlassian Document Format) Support

The server automatically converts plain text and markdown to ADF format:

Plain Text

description = "Simple text description"

Markdown

description = """
## Overview
This issue implements **important** features.

### Acceptance Criteria
- First criterion
- Second criterion

```python
def example():
    return "code block"

"""

### Structured Descriptions
```python
from adf_utils import create_issue_description

description = create_issue_description(
    overview="Main description",
    acceptance_criteria=["AC1", "AC2", "AC3"],
    technical_details="Implementation notes",
    notes="Additional information"
)

JQL Examples

# My open issues
search_issues(jql="assignee = currentUser() AND statusCategory != Done")

# High priority bugs
search_issues(jql="priority = High AND issuetype = Bug")

# Sprint backlog
search_issues(jql="sprint in openSprints() AND project = PROJ")

# Recent comments
search_issues(jql="comment ~ 'search text' AND updated >= -7d")

Error Handling

The server provides detailed error messages from Jira's API:

try:
    result = await create_issue(...)
except Exception as e:
    # Error message includes field-specific validation errors
    print(f"Error: {e}")

Architecture

atlassian-jira-mcp-server/
├── server.py          # FastMCP server initialization
├── tools.py           # 17 tool implementations
├── resources.py       # 8 resource endpoints
├── adf_utils.py       # ADF formatting utilities
├── utils/
│   ├── auth.py        # Authentication handling
│   ├── config.py      # Configuration management
│   └── api_client.py  # Jira API client
└── requirements.txt   # Dependencies

Development

Running Tests

pytest tests/

Adding New Tools

1. Implement in tools.py:

async def new_tool(param: str) -> dict:
    """Tool implementation"""
    return await make_request("GET", f"endpoint/{param}")

2. Register in server.py:

@mcp.tool(description="Tool description")
async def new_tool(param: str) -> dict:
    return await tools.new_tool(param)

Troubleshooting

Installation Issues

"externally-managed-environment" Error

× This environment is externally managed

Solution: Use Method 1 (uv tool) or Method 2 (virtual environment) instead of direct pip installation.

"ModuleNotFoundError: No module named 'prompts'" with uv tool

This was a packaging issue that has been fixed. If you encounter this:

uv tool uninstall atlassian-jira-mcp-server
uv tool install . --force --reinstall

Python/pip not found with pyenv

pyenv: python: command not found

Solution: Either set a global Python version or use python3 explicitly:

# Set global Python version
pyenv global 3.12.11

# Or use python3 directly
python3 -m venv .venv
source .venv/bin/activate

Authentication Issues

• Ensure your API token is valid
• Check JIRA_BASE_URL includes https://
• Verify email address matches Jira account

Permission Errors

• Confirm user has appropriate Jira permissions
• Check project access rights
• Verify issue type availability in project

ADF Formatting

• Use convert_to_adf() for automatic conversion
• Check jira://adf-examples resource for examples
• Validate ADF structure with is_adf_format()

Development Issues

After Code Changes

Always reinstall after making changes:

# UV tool method
uv tool uninstall atlassian-jira-mcp-server && uv tool install . --reinstall

# Virtual environment method
source .venv/bin/activate && pip install -e .

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• Report issues
• Jira Cloud API Documentation
• MCP Documentation
• FastMCP Documentation