Skip to main content
Glama

Simple Jira MCP

A Model Context Protocol (MCP) server that provides Jira Cloud integration for AI agents.

Features

  • Search issues using JQL (Jira Query Language)

  • Retrieve issue details with comments and attachments

  • Create, update, and delete issues

  • List available transitions and transition issues with screen fields

  • Add comments, including comments posted with a transition

  • List sprints and move issues into a sprint

  • Download attachments

  • Connect to multiple Jira instances

Related MCP server: Jira MCP Server

Choosing this server

Use this server to run Jira tools locally with your API token:

  • Connect to multiple Jira instances through JIRA_CONFIG_JSON and select one with config_id.

  • Download attachments to disk.

  • Search, read, create, update, delete, transition, and comment on issues through twelve tools.

  • Choose search response fields and read descriptions and comments as plain text.

You install and maintain the server. It supports Jira Cloud and uses the configured API token for each instance. It does not support per-user OAuth or other Atlassian products.

See Atlassian's official MCP server for an alternative.

Requirements

  • Python 3.11+

  • Jira Cloud account with API token

Installation

git clone https://github.com/timohaa/simple-jira-mcp.git
cd simple-jira-mcp
python -m venv venv

# Linux/macOS
source venv/bin/activate

# Windows
# venv\Scripts\activate

pip install -e ".[dev]"

Configuration

Set the JIRA_CONFIG_JSON environment variable with your Jira credentials:

export JIRA_CONFIG_JSON='[
  {
    "id": "work",
    "url": "https://your-domain.atlassian.net",
    "email": "your-email@example.com",
    "token": "your-api-token",
    "timeout": 60
  }
]'

Generate an API token at: https://id.atlassian.com/manage-profile/security/api-tokens

Set timeout per instance to limit each HTTP phase in seconds. It defaults to 30 and must be positive. Raise it for slow connections. See API_REFERENCE.md for details.

Use an https:// URL to protect the API token in transit. Each entry must have non-empty id, url, email, and token values. IDs must be unique. The server refuses to start if any entry violates these rules.

AI Tool Integration

In every snippet below, replace /path/to/simple-jira-mcp with your checkout path. Set command to the venv interpreter created during installation. Using a bare python requires the client to select an interpreter with the server's dependencies installed.

Installation also creates a venv/bin/simple-jira-mcp script. You can use its path as command with no args in place of the interpreter and -m simple_jira_mcp.

When upgrading from 0.5.0 or earlier, change the module name in your client config. Replace "args": ["-m", "src"] with "args": ["-m", "simple_jira_mcp"] and rerun pip install -e ".[dev]".

Set cwd to choose where download_attachment saves files when output_dir is omitted. Without cwd, downloads use the directory from which the client launched the server. The installed package can start from any directory.

Claude Desktop

Platform

Config Path

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "jira": {
      "command": "/path/to/simple-jira-mcp/venv/bin/python",
      "args": ["-m", "simple_jira_mcp"],
      "cwd": "/path/to/simple-jira-mcp",
      "env": {
        "JIRA_CONFIG_JSON": "[{\"id\": \"work\", \"url\": \"https://your-domain.atlassian.net\", \"email\": \"your-email@example.com\", \"token\": \"your-api-token\"}]"
      }
    }
  }
}

Claude Code (CLI)

Edit ~/.claude.json:

{
  "mcpServers": {
    "jira": {
      "command": "/path/to/simple-jira-mcp/venv/bin/python",
      "args": ["-m", "simple_jira_mcp"],
      "cwd": "/path/to/simple-jira-mcp",
      "env": {
        "JIRA_CONFIG_JSON": "[{\"id\": \"work\", \"url\": \"https://your-domain.atlassian.net\", \"email\": \"your-email@example.com\", \"token\": \"your-api-token\"}]"
      }
    }
  }
}

Verify with claude mcp list.

Gemini CLI

Config file: ~/.gemini/settings.json

{
  "mcpServers": {
    "jira": {
      "command": "/path/to/simple-jira-mcp/venv/bin/python",
      "args": ["-m", "simple_jira_mcp"],
      "cwd": "/path/to/simple-jira-mcp",
      "env": {
        "JIRA_CONFIG_JSON": "[{\"id\": \"work\", \"url\": \"https://your-domain.atlassian.net\", \"email\": \"your-email@example.com\", \"token\": \"your-api-token\"}]"
      }
    }
  }
}

Verify with /mcp command in Gemini CLI.

OpenAI Codex CLI

Config file: ~/.codex/config.toml

[mcp_servers.jira]
command = "/path/to/simple-jira-mcp/venv/bin/python"
args = ["-m", "simple_jira_mcp"]
cwd = "/path/to/simple-jira-mcp"

[mcp_servers.jira.env]
JIRA_CONFIG_JSON = '[{"id": "work", "url": "https://your-domain.atlassian.net", "email": "your-email@example.com", "token": "your-api-token"}]'

Cursor

Scope

Config Path

Global

~/.cursor/mcp.json

Project

.cursor/mcp.json

{
  "mcpServers": {
    "jira": {
      "command": "/path/to/simple-jira-mcp/venv/bin/python",
      "args": ["-m", "simple_jira_mcp"],
      "cwd": "/path/to/simple-jira-mcp",
      "env": {
        "JIRA_CONFIG_JSON": "[{\"id\": \"work\", \"url\": \"https://your-domain.atlassian.net\", \"email\": \"your-email@example.com\", \"token\": \"your-api-token\"}]"
      }
    }
  }
}

Access via Cursor Settings > MCP.

Windsurf (Codeium)

Platform

Config Path

macOS/Linux

~/.codeium/windsurf/mcp_config.json

Windows

%USERPROFILE%\.codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "jira": {
      "command": "/path/to/simple-jira-mcp/venv/bin/python",
      "args": ["-m", "simple_jira_mcp"],
      "cwd": "/path/to/simple-jira-mcp",
      "env": {
        "JIRA_CONFIG_JSON": "[{\"id\": \"work\", \"url\": \"https://your-domain.atlassian.net\", \"email\": \"your-email@example.com\", \"token\": \"your-api-token\"}]"
      }
    }
  }
}

Access via Windsurf Settings > Cascade > Plugins (MCP servers).

VS Code with GitHub Copilot

Config file: .vscode/mcp.json (project-level)

{
  "servers": {
    "jira": {
      "command": "/path/to/simple-jira-mcp/venv/bin/python",
      "args": ["-m", "simple_jira_mcp"],
      "cwd": "/path/to/simple-jira-mcp",
      "env": {
        "JIRA_CONFIG_JSON": "[{\"id\": \"work\", \"url\": \"https://your-domain.atlassian.net\", \"email\": \"your-email@example.com\", \"token\": \"your-api-token\"}]"
      }
    }
  }
}

Requires VS Code 1.102+ with GitHub Copilot. Use Agent Mode in Copilot Chat.

Zed

Add to Zed settings.json:

{
  "context_servers": {
    "jira": {
      "command": "/path/to/simple-jira-mcp/venv/bin/python",
      "args": ["-m", "simple_jira_mcp"],
      "env": {
        "JIRA_CONFIG_JSON": "[{\"id\": \"work\", \"url\": \"https://your-domain.atlassian.net\", \"email\": \"your-email@example.com\", \"token\": \"your-api-token\"}]"
      }
    }
  }
}

Pass output_dir to download_attachment when using this snippet, which omits cwd. Otherwise, downloads use the directory from which Zed launched the server.

Windows Notes

On Windows, use full paths with backslashes:

{
  "command": "C:\\path\\to\\simple-jira-mcp\\venv\\Scripts\\python.exe",
  "cwd": "C:\\path\\to\\simple-jira-mcp"
}

Available Tools

Tool

Description

list_configs

List available Jira configurations

search_issues

Search issues using JQL

get_issue

Get detailed issue information

create_issue

Create a new issue

update_issue

Change fields on an issue

delete_issue

Permanently delete an issue

get_transitions

List transitions and screen fields

transition_issue

Transition an issue by ID or name

add_comment

Add a plain-text comment

list_sprints

List sprints of a project or board

move_issues_to_sprint

Move issues into a sprint

download_attachment

Download an attachment from an issue

Usage Notes

  • list_configs: Returns each config's effective timeout and marks the first entry in JIRA_CONFIG_JSON with default: true. With no configs loaded, it returns {"configs": []}. It never returns an error. The server exits at startup when JIRA_CONFIG_JSON is unset or empty.

  • search_issues: JQL must include at least one bounding filter (project, status, assignee, reporter, priority, type/issuetype, key, id, or a created/updated/resolved clause). Any one satisfies the check. A project filter is optional. Quote values that are JQL reserved words: project = "ON", not project = ON. Semicolons and newlines are rejected. Supports cursor pagination with next_page_token and is_last (the Jira /search/jql endpoint returns no total count). The optional fields allowlist is forwarded to Jira and determines the response fields. Each issue contains key, url, and only the requested fields. Default fields are summary, status, assignee, priority, updated, created, labels, issuetype.

  • get_issue: include_comments and include_attachments toggle those sections. Descriptions and comments are plain text; attachments include size_kb and mime_type.

  • create_issue: Accepts a summary up to 255 characters and converts the description to ADF. priority, labels, and assignee_account_id are optional.

  • update_issue: Omitted parameters stay unchanged. labels replaces the current labels. An empty description blanks the description. Other fields go in fields in Jira REST format, where a null value clears the field ({"assignee": null} unassigns). Status changes go through transition_issue.

  • delete_issue: Permanently deletes the issue. Jira cannot restore it. An issue with subtasks is deleted only when delete_subtasks is true. The API token's user needs the Delete Issues permission in the project.

  • get_transitions: Returns transition IDs, names, target statuses, and screen field metadata with required flags and allowed values.

  • transition_issue: Accepts an ID or case-insensitive transition/target-status name. Ambiguous names return valid options. Optional resolution and fields must be accepted by the screen. An optional plain-text comment is posted in the same request when the screen accepts comments. Otherwise, it is posted immediately after the transition. Returns status, resolution, and resolutiondate from Jira. Jira sets resolutiondate itself; the API cannot edit it. Record the actual completion date in the comment.

  • add_comment: Converts plain text to ADF and returns the comment ID and creation time.

  • list_sprints: Needs project_key or board_id (board_id wins). Lists sprints through the Jira Agile API, across all of a project's boards, filtered by state (default active,future; also closed). Returns id, name, state, startDate, endDate, boardId, and boardName.

  • move_issues_to_sprint: Moves issues into the sprint sprint_id, sending at most 50 per request. Returns the sprint ID and the moved keys. Use list_sprints to find the sprint ID.

  • download_attachment: output_dir must exist when provided. It defaults to the current working directory. Files are saved to <output_dir>/<issue_key>/ with sanitized filenames. If the filename is already taken, the attachment ID is appended (log-10042.txt).

  • Errors: a failed call sets the MCP result's isError flag and carries {"isError": true, "error": {"code": ..., "message": ...}} as its content.

Reference

See API_REFERENCE.md for tool inputs/outputs, error codes, and JQL patterns.

Development

# Run all checks (lint, type check, tests)
./check.sh

# Run specific checks
./check.sh -l    # Linting only
./check.sh -m    # Type checking only
./check.sh -t    # Tests only
./check.sh -c    # Tests with coverage
./check.sh -f    # Auto-fix linting issues
./check.sh -a    # Explicitly run all checks
./check.sh -h    # Show help

License

MIT License - see LICENSE for details.

Available Tools

12 tools
add_commentAdd Jira commentB

Add a plain-text comment to a Jira issue. Returns ID and created.

Inputs: body (required), issue_key (required), config_id.

create_issueCreate Jira issueB

Create a Jira issue. Returns issue key and URL.

Inputs: summary (required), project_key (required), labels, priority, +4 more.

delete_issueDelete Jira issueA
DestructiveIdempotent

Permanently delete a Jira issue. Jira cannot restore it. An issue with subtasks is only deleted when delete_subtasks is true.

Inputs: issue_key (required), config_id, delete_subtasks.

download_attachmentDownload Jira attachmentC

Download an attachment from a Jira issue to a local file.

Inputs: issue_key (required), attachment_id (required), config_id, output_dir.

get_issueGet Jira issueB
Read-only

Get full details for a Jira issue by key (e.g., ONE-123).

Inputs: issue_key (required), config_id, include_comments, include_attachments.

get_transitionsGet Jira issue transitionsA
Read-only

Get available transitions for a Jira issue. Returns transition IDs, names, target statuses, and screen fields with required flags and allowed values.

Inputs: issue_key (required), config_id.

list_configsList Jira configurationsA
Read-only

List configured Jira instances and their config_id values.

Inputs: no named parameters.

list_sprintsList Jira sprintsA
Read-only

List sprints of a Jira board, or of every board in a project, using the Agile API. Give project_key or board_id. state is a comma-separated filter of active, future, closed. Returns sprint id, name, state, startDate, endDate, boardId, and boardName. Use an id with move_issues_to_sprint.

Inputs: state, board_id, config_id, project_key.

move_issues_to_sprintMove Jira issues to sprintA

Move issues into a sprint (Agile API), in batches of 50. Get the sprint ID from list_sprints. Returns the sprint ID and the moved issue keys.

Inputs: sprint_id (required), issue_keys (required), config_id.

search_issuesSearch Jira issuesA
Read-only

Search issues using JQL. Include at least one bounding clause: project, status, assignee, reporter, priority, type/issuetype, key, id, or created/updated/resolved. A project filter is optional. Quote JQL reserved values, for example project = "ON".

Inputs: jql (required), limit, fields, config_id, +1 more.

transition_issueTransition Jira issueA

Transition a Jira issue using a transition ID or a case-insensitive transition or target status name. An optional plain-text comment is posted with the transition when the screen accepts comments. Otherwise, it is posted immediately afterwards. Resolution and fields must be accepted by the transition screen. Returns the new status, resolution, and resolutiondate. Jira sets resolutiondate itself. The API cannot edit it. Record the actual completion date in the comment.

Inputs: issue_key (required), transition (required), fields, comment, +2 more.

update_issueUpdate Jira issueA
DestructiveIdempotent

Update fields on a Jira issue. Omitted parameters stay unchanged. Labels replace the current set. Pass other Jira fields through fields. Use a null value to clear a field, e.g. {"assignee": null}. Returns the updated field IDs. To change status, use transition_issue.

Inputs: issue_key (required), fields, labels, summary, +4 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool maps to a distinct resource+action: issue CRUD (create/get/update/delete), workflow (get_transitions/transition_issue), comments, attachments, sprints, search, and config listing. The only potential overlap—update_issue vs. transition_issue—is explicitly resolved in the descriptions, which state that status changes go through transition_issue.

    Naming Consistency5/5

    All 12 tools follow a strict verb_noun snake_case pattern (create_issue, get_issue, list_sprints, move_issues_to_sprint). No mixed conventions or vague verbs appear.

    Tool Count5/5

    12 tools is well within the sweet spot and every tool earns its place: issue lifecycle, transitions, comments, attachments, sprints, search, and config discovery. No redundant or filler tools are present.

    Completeness4/5

    The issue lifecycle is fully covered (create/get/update/delete/search/transition) plus comments, sprints, and attachments. Gaps exist—no attachment upload, no comment edit/delete, no sprint or board creation, and no project/user lookup—but agents can work around most of these or fail gracefully.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to interact with Jira Cloud instances for comprehensive issue management including creating, updating, searching issues, managing comments, workflow transitions, and project metadata discovery. Supports JQL queries, user search, and custom field operations with secure API token authentication.
      12
      611 npm
      8
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Integrates with Jira Cloud to enable comprehensive issue management, project tracking, and team collaboration through natural language, including creating/updating tickets, searching with JQL, managing workflows, and adding comments.
      8
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with Jira Cloud through the REST API, supporting project management, issue operations (create, read, update, delete), JQL search, task assignments, and status transitions.
      -