Build a Jira MCP Server

Download Lab Files

Build your own MCP server in Python to connect Claude Desktop to Jira. Create User Stories, update issues and more.

What You'll Build

Search Issues (JQL)

Query Jira with natural language

Create User Stories

Create tickets directly from Claude

Update & Transition

Change status and update fields

Add Comments

Comment on issues via Claude

Step 1: Get Atlassian API Token

Go to Atlassian Security Settings
Click Create API token
Label it (e.g., "mcp-jira-claude")
Copy the token (you won't see it again)

Keep these handy: Email, API Token, and Jira URL (e.g., https://yourcompany.atlassian.net)

Step 2: Environment Setup

Recommended: Docker ensures consistent environment and includes all dependencies.

# 1. Navigate to the directory
cd Handson/mcp-jira-server

# 2. Configure environment
cp .env.example .env
# Edit .env with your Jira URL, Email, and API Token

# 3. Build and run with Docker Compose
docker-compose up --build -d

# 4. Test the server
docker exec -it mcp-jira-server python main.py

# Navigate to the directory
cd Handson/mcp-jira-server

# Configure Poetry
poetry config virtualenvs.in-project true

# Install dependencies
poetry install

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Test the server
poetry run python main.py

# Navigate to the directory
cd Handson/mcp-jira-server

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

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Test the server
python main.py

Step 3: Configure Claude Desktop

Edit your claude_desktop_config.json to point to your local Python script.

Config location (macOS):
~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "jira-local": {
      "command": "/ABSOLUTE/PATH/TO/PROJECT/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/PROJECT/Handson/mcp-jira-server/main.py"],
      "env": {
         "JIRA_URL": "https://your-domain.atlassian.net",
         "JIRA_EMAIL": "your-email@example.com",
         "JIRA_API_TOKEN": "your-api-token-here",
         "JIRA_DEFAULT_PROJECT_KEY": "ABC"
      }
    }
  }
}

Important: You must use absolute paths for both the python executable (in the virtual env) and the script file. Restart Claude Desktop after saving.

Step 4: Use with Claude

Restart Claude Desktop and try these prompts:

"Search for the 5 most recent bugs in project ABC"

"Create a user story in project ABC: 'Login with Google', 'As a user I want to login with Google...'"

"Transition issue ABC-123 to 'In Progress'"

Project Structure

mcp-jira-server/
├── main.py              # MCP server with FastMCP tools
├── jira_client.py       # Async Jira REST client
├── pyproject.toml       # Poetry configuration
├── Dockerfile           # Docker build configuration
├── docker-compose.yml   # Docker Compose setup
├── .env.example         # Environment variables template
├── requirements.txt     # Pip dependencies
└── README.md            # Documentation

MCP Tools Exposed

Tool	Description
`jira_search_issues`	Search issues using JQL
`jira_get_issue`	Get details of a specific issue
`jira_create_user_story`	Create a new User Story
`jira_update_issue`	Update an existing issue
`jira_add_comment`	Add a comment to an issue
`jira_list_transitions`	List available status transitions
`jira_transition_issue`	Change the status of an issue

Additional Resources

MCP Documentation Jira REST API v3 Claude Desktop MCP + PDF Search (Related Lab)