Simple Jira MCP
Provides integration with Jira Cloud, enabling AI agents to search for issues using JQL, retrieve detailed issue information including comments and attachments, create new issues, and download attachments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Simple Jira MCP search for all open bugs assigned to me"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_JSONand select one withconfig_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 |
|
Linux |
|
Windows |
|
{
"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 |
|
Project |
|
{
"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 |
|
Windows |
|
{
"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 available Jira configurations |
| Search issues using JQL |
| Get detailed issue information |
| Create a new issue |
| Change fields on an issue |
| Permanently delete an issue |
| List transitions and screen fields |
| Transition an issue by ID or name |
| Add a plain-text comment |
| List sprints of a project or board |
| Move issues into a sprint |
| Download an attachment from an issue |
Usage Notes
list_configs: Returns each config's effectivetimeoutand marks the first entry inJIRA_CONFIG_JSONwithdefault: true. With no configs loaded, it returns{"configs": []}. It never returns an error. The server exits at startup whenJIRA_CONFIG_JSONis 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", notproject = ON. Semicolons and newlines are rejected. Supports cursor pagination withnext_page_tokenandis_last(the Jira/search/jqlendpoint returns no total count). The optionalfieldsallowlist is forwarded to Jira and determines the response fields. Each issue containskey,url, and only the requested fields. Default fields are summary, status, assignee, priority, updated, created, labels, issuetype.get_issue:include_commentsandinclude_attachmentstoggle those sections. Descriptions and comments are plain text; attachments includesize_kbandmime_type.create_issue: Accepts a summary up to 255 characters and converts the description to ADF.priority,labels, andassignee_account_idare optional.update_issue: Omitted parameters stay unchanged.labelsreplaces the current labels. An emptydescriptionblanks the description. Other fields go infieldsin Jira REST format, where anullvalue clears the field ({"assignee": null}unassigns). Status changes go throughtransition_issue.delete_issue: Permanently deletes the issue. Jira cannot restore it. An issue with subtasks is deleted only whendelete_subtasksis 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. Optionalresolutionandfieldsmust be accepted by the screen. An optional plain-textcommentis posted in the same request when the screen accepts comments. Otherwise, it is posted immediately after the transition. Returns status, resolution, andresolutiondatefrom Jira. Jira setsresolutiondateitself; 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: Needsproject_keyorboard_id(board_idwins). Lists sprints through the Jira Agile API, across all of a project's boards, filtered bystate(defaultactive,future; alsoclosed). Returnsid,name,state,startDate,endDate,boardId, andboardName.move_issues_to_sprint: Moves issues into the sprintsprint_id, sending at most 50 per request. Returns the sprint ID and the moved keys. Uselist_sprintsto find the sprint ID.download_attachment:output_dirmust 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
isErrorflag 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 helpLicense
MIT License - see LICENSE for details.
Available Tools
12 toolsadd_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 issueADestructiveIdempotent
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 issueBRead-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 transitionsARead-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 configurationsARead-only
List configured Jira instances and their config_id values.
Inputs: no named parameters.
list_sprintsList Jira sprintsARead-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 issuesARead-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 issueADestructiveIdempotent
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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
Connect to Atlassian Jira, Confluence, Loom, and more to search, create, and manage your work.
Task manager your agent can fully operate: boards, tasks, sprints, roles, worklogs, day planner.
Task and bug tracker for AI coding agents: 75 tools to file, triage and update work.
Use your connected apps from your agent: search synced data, act in apps and set up automations.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.12611 npm8MIT
- FlicenseAqualityDmaintenanceIntegrates 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-
- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- AlicenseAqualityDmaintenanceEnables AI agents to interact with Jira Cloud, including listing boards and issues, adding comments, and searching users.72MIT