Skip to main content
Glama
deenesjakoruzh
vaspap1790

jira-mcp

by vaspap1790
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Jira MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Jira. Enables Cursor and other MCP clients to fetch tickets, manage linked tickets, and update ticket status.

Quick Start

1. Install Dependencies

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install project dependencies
uv sync

2. Configure Jira Credentials

Recommended: Personal Access Token (PAT)

  1. Log into Jira: https://jira.telekom.de

  2. Go to your profile > Personal Access Tokens

  3. Click "Create token"

  4. Give it a name (e.g., "Cursor MCP") and set expiration

  5. Important: Ensure the token has "Read" or "Browse Projects" permissions

  6. Copy the token immediately (you won't see it again)

Create .env file:

cp .env.example .env

Edit .env with your credentials:

JIRA_URL=https://jira.telekom.de
JIRA_USERNAME=your.username@telekom.de
JIRA_API_TOKEN=your_personal_access_token_here
JIRA_AUTH_TYPE=bearer

Note: Kantega SSO API tokens may have IP restrictions or require admin-configured permissions. Personal Access Tokens are recommended for most users.

3. Configure in Cursor

  1. Open Cursor

  2. Go to Settings > Tools and MCP

  3. Add this configuration:

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/jira-mcp",
        "run",
        "-m",
        "src"
      ]
    }
  }
}

Important: Replace the path and credentials with your actual values!

  1. Restart Cursor completely

4. Try It Out

In Cursor chat, try:

  • "Get details for Jira ticket PROJ-123"

  • "Show me all linked tickets for PROJ-456"

  • "Update PROJ-789 status to In Progress"

Related MCP server: JIRA MCP Server

Features

Available Tools

Tool

Description

Example

get_ticket

Fetch full ticket details

"Get PROJ-123"

get_linked_tickets

Get related tickets & subtasks

"Show linked tickets for PROJ-123"

update_ticket_status

Update ticket status

"Move PROJ-123 to In Progress"

Authentication Support

  • Bearer Token: Personal Access Tokens (PAT) - Recommended

  • Basic Auth: Username + API token (Atlassian Cloud)

  • Cookie Auth: Session-based authentication (fallback option)

Tool Details

get_ticket

Fetches complete ticket information.

Parameters:

  • ticket_id (string, required): Ticket ID or key (e.g., "PROJ-123")

Returns:

{
  "key": "PROJ-123",
  "summary": "Ticket summary",
  "description": "Detailed description",
  "status": "In Progress",
  "issue_type": "Story",
  "priority": "High",
  "assignee": "John Doe",
  "reporter": "Jane Smith",
  "created": "2024-01-15T10:30:00.000+0000",
  "updated": "2024-01-20T14:45:00.000+0000",
  "comments_count": 3,
  "comments": [...],
  "custom_fields": {...}
}

get_linked_tickets

Fetches all related tickets and subtasks.

Parameters:

  • ticket_id (string, required): Ticket ID or key

Returns:

{
  "ticket": "PROJ-123",
  "linked_tickets": [
    {
      "link_type": "Blocks",
      "direction": "blocks",
      "key": "PROJ-124",
      "summary": "Related ticket",
      "status": "To Do"
    }
  ],
  "linked_tickets_count": 1,
  "subtasks": [...],
  "subtasks_count": 2
}

update_ticket_status

Updates ticket status with workflow validation.

Parameters:

  • ticket_id (string, required): Ticket ID or key

  • status (string, required): Target status (e.g., "In Progress", "Done")

Returns:

Successfully updated ticket PROJ-123 status from 'To Do' to 'In Progress'

Note: The tool validates transitions. If invalid, it returns available transitions.

Testing

Run Tests

# Run all tests
.venv/bin/pytest tests/ -v

# Run with coverage
.venv/bin/pytest tests/ --cov=src -v

# Run specific test file
.venv/bin/pytest tests/test_integration/test_real_tickets.py -v

Manual Testing

Test the server directly:

uv run --env-file .env -m src

Press Ctrl+C to stop.

Troubleshooting

Authentication Errors

Symptoms: "401 Unauthorized" or "403 Forbidden"

Solutions:

  • Most common: Personal Access Token is expired - generate a new one

  • Verify your PAT has "Read" or "Browse Projects" permissions

  • Check your username matches your Jira account email

  • Ensure JIRA_URL includes https://

  • Confirm JIRA_AUTH_TYPE=bearer for Personal Access Tokens

Ticket Not Found

Symptoms: "404 Not Found"

Solutions:

  • Verify the ticket key is correct (e.g., "PROJ-123")

  • Check you have permission to view the ticket

  • Ensure you're using the correct Jira instance

Server Not Appearing in Cursor

Solutions:

  • Verify the absolute path in your MCP settings

  • Check Python 3.12+ is installed: python3 --version

  • Restart Cursor completely (quit and reopen)

  • Check Cursor's developer console for errors

Cannot Transition Ticket

Symptoms: "Invalid status transition"

Solutions:

  • The error message lists available transitions

  • Status names must match exactly (case-insensitive)

  • Check your Jira workflow permissions

  • Verify the transition is valid for your workflow

Architecture

This project follows SOLID principles and clean architecture:

src/
├── __init__.py
├── __main__.py           # Entry point
├── server.py             # MCP server setup
├── config/               # Configuration management
├── client/               # Jira API client
├── tools/                # 3 MCP tools
├── models/               # Domain models
├── mappers/              # Data transformation
└── utils/                # Error handling, JSON utils

Key Principles:

  • SOLID: Single responsibility, dependency inversion

  • DRY: No duplication, reusable components

  • Type Safety: Full type hints throughout

  • Testable: Clean separation of concerns

See ARCHITECTURE.md for detailed technical documentation.

Development

Project Structure

jira-mcp/
├── src/                  # Source code (22 Python files)
├── tests/                # Test suite
├── pyproject.toml        # Project config (includes pytest config)
├── .env.example          # Config template
├── .gitignore
├── README.md             # This file
└── ARCHITECTURE.md       # Technical docs

Adding Dependencies

uv add package-name

Running with Different Config

uv run --env-file .env.production -m src

Code Quality

  • Linting errors: 0

  • Type coverage: 100%

  • Test coverage: Integration tests for all 3 tools

  • Architecture: SOLID + DRY compliant

Requirements

  • Python 3.12+

  • Jira account with API access

  • Jira API token (Kantega SSO Enterprise or Atlassian Cloud)

License

This project is provided as-is for use with Cursor and Jira.

Built with best practices following SOLID and DRY principles 🚀

Available Tools

3 tools
get_linked_ticketsA

Fetch all linked tickets and subtasks for a given Jira ticket. Returns issue links (blocks, is blocked by, relates to, etc.) and subtasks with their summaries and statuses.

ParametersJSON Schema
NameRequiredDescriptionDefault
ticket_idYesThe Jira ticket ID or key (e.g., 'PROJ-123')

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses what is returned (issue links and subtasks with summaries and statuses) but lacks details on authorization, pagination, or limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose followed by output details. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one required parameter and no output schema, the description covers purpose, parameter, and return structure. It lacks error handling or clarification on depth of links, but is relatively complete for a simple fetch tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema coverage is 100% with a description of ticket_id. The description adds an example format ('e.g., 'PROJ-123'') but does not provide additional semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Fetch' and the resource 'all linked tickets and subtasks for a given Jira ticket', distinguishing it from siblings like get_ticket which returns a single ticket.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing linked tickets or subtasks, but does not explicitly state when to use this tool versus alternatives like get_ticket or update_ticket_status.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_ticketA

Fetch full details of a Jira ticket by its ID or key. Returns comprehensive ticket information including summary, description, status, issue type, priority, assignee, reporter, comments, and custom fields.

ParametersJSON Schema
NameRequiredDescriptionDefault
ticket_idYesThe Jira ticket ID or key (e.g., 'PROJ-123')

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description discloses that the tool fetches (read operation) and lists returned fields, but does not mention rate limits, required permissions, error cases, or side effects. It adds value over schema by specifying return contents but lacks full behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first states action and input, second lists outputs. No extraneous words, front-loaded, and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema, the description provides a good overview of return content (summary, description, status, etc.). Minor gap: custom fields are vague and exact structure not detailed, but sufficient for basic understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a description for ticket_id. The description reiterates 'by its ID or key' without adding new meaning beyond the schema's example. Hence, baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it fetches full details of a Jira ticket by ID or key and lists returned information (summary, status, etc.). It distinguishes from sibling tools ('get_linked_tickets', 'update_ticket_status') implicitly by resource and verb, but does not explicitly contrast them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (when you need ticket details) but does not explicitly state when not to use or suggest alternatives like get_linked_tickets for linked issues.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_ticket_statusA

Update the status of a Jira ticket by transitioning it to a new status. Validates that the transition is valid for the ticket's current workflow. Common statuses include: 'To Do', 'In Progress', 'In Review', 'Done'.

ParametersJSON Schema
NameRequiredDescriptionDefault
ticket_idYesThe Jira ticket ID or key (e.g., 'PROJ-123')
statusYesThe target status name (e.g., 'In Progress', 'Done')

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It mentions validation of transitions, but does not disclose side effects (e.g., notifications), permissions requirements, idempotency, or error handling behavior. This is adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the action, and contains no redundant information. Every sentence contributes meaningful context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 params, no nested objects), the description is mostly complete. However, it omits the return value or success/error behavior, which would be helpful since there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, earning a baseline of 3. The description adds value by listing common statuses ('To Do', 'In Progress', 'In Review', 'Done'), which provides context beyond the schema's generic description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Update the status of a Jira ticket by transitioning it to a new status') and differentiates from sibling read-only tools like 'get_linked_tickets' and 'get_ticket'. It also provides examples of common statuses, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by mentioning validation of transitions, but does not explicitly state when to use or avoid this tool, nor does it provide alternatives beyond the obvious sibling tools. It lacks guidance on prerequisites or edge cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedget_linked_tickets
    • First observedget_ticket
    • First observedupdate_ticket_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct operation: retrieving a ticket, fetching linked tickets, and updating status. No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent 'verb_noun' pattern in snake_case (get_ticket, get_linked_tickets, update_ticket_status), making them predictable.

Tool Count4/5

Three tools is on the lower end of the ideal range but still reasonable for a focused Jira server. Each tool serves a clear purpose without feeling sparse.

Completeness2/5

Missing essential CRUD operations such as create_ticket, search_tickets, or add_comment. Agents cannot create new tickets or perform most lifecycle actions.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • JIRA MCP Server

    Dsazz
    A
    license
    B
    quality
    D
    maintenance
    A Model Context Protocol server that integrates JIRA directly into Cursor IDE, allowing users to view assigned issues, get detailed information on specific tickets, and convert JIRA issues into local tasks without leaving their editor.
    14
    12 npm
    6
    TypeScript
    MIT

  • Jira MCP Server

    maximepeabody
    A
    license
    Not graded
    quality
    D
    maintenance
    A Simple Model Context Protocol server that enables AI assistants to interact with Jira, allowing operations like fetching tickets, adding comments, and updating ticket status.
    1
    Apache 2.0

  • MCP Jira

    TusharShahi
    F
    license
    Not graded
    quality
    D
    maintenance
    Model Context Protocol server that allows AI assistants to interact with Jira, supporting operations like creating tickets and fetching project information directly from the cursor.
    1
    -