PJSathischandar/jira-mcp-server

Jira MCP Server

A Model Context Protocol (MCP) server for interacting with Jira Cloud instances. This server provides tools and resources to search, create, update, and manage Jira issues through the MCP protocol.

Features

Tools

• search_issues(jql, max_results=50) - Search issues using JQL queries
• get_issue(issue_key) - Fetch a single issue by key
• create_issue(project_key, summary, description, ...) - Create new issues
• comment_issue(issue_key, comment) - Add comments to issues
• transition_issue(issue_key, transition) - Move issues through workflow states
• get_transitions(issue_key) - Get available transitions for an issue
• assign_issue(issue_key, account_id, assignee_email) - Assign issues to users
• add_label(issue_key, label) - Add labels to issues

Resources (read-only)

• issue://{key} - Get issue details by key
• jql://{query} - Run JQL searches

Prerequisites

• Python 3.8+
• Jira Cloud instance with API access
• Jira API token

Installation

1. Clone the repository:

git clone <repository-url>
cd jira-agent

2. Install dependencies:

pip install -r requirements.txt

3. Set up environment variables:

cp .env.example .env

Edit .env with your Jira credentials:

JIRA_BASE=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-api-token

Getting Your Jira API Token

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a label and copy the generated token
4. Use this token in your .env file

Usage

Running the Server

For MCP clients (like Claude Desktop):

python jira-mcp.py

Testing with MCP Dev Inspector

mcp dev jira-mcp.py

Configuration for Claude Desktop

Add this to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["/path/to/jira-agent/jira-mcp.py"],
      "cwd": "/path/to/jira-agent"
    }
  }
}

Examples

Searching Issues

# Search for issues in a specific project
search_issues("project = PROJ AND status = 'To Do'")

# Search for your assigned issues
search_issues("assignee = currentUser() AND status != Done")

Creating Issues

create_issue(
    project_key="PROJ",
    summary="Fix login bug",
    description="Users unable to login with special characters",
    issuetype="Bug",
    priority="High"
)

Working with Transitions

# Get available transitions
get_transitions("PROJ-123")

# Move issue to In Progress
transition_issue("PROJ-123", "In Progress")

Notes

• For Jira Cloud, user assignment requires accountId (not username/email)
• Comments use Atlassian Document Format (ADF)
• The server uses Jira REST API v3

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details