www-jira-mcp

MCP (Model Context Protocol) server providing Jira Server/Data Center integration — issue management, search, projects, comments, transitions, links, worklogs, attachments, and more.

Gives AI assistants (Qoder, Claude Desktop, Cursor, etc.) the ability to read and write Jira issues and projects through a single MCP server with 47 tools, 5 resources, and 3 prompt templates.

Note: This server targets Jira Server/Data Center only (REST API v2). Jira Cloud is not supported.

System Requirements

Install uv

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS (Homebrew):

brew install uv

Installation

Option 1: Run directly with uvx (recommended)

No clone needed. Runs from PyPI. Updates automatically on each run:

uvx www-jira-mcp

MCP client config:

{
  "mcpServers": {
    "www-jira-mcp": {
      "command": "uvx",
      "args": ["www-jira-mcp"],
      "env": {
        "JIRA_URL": "https://jira.example.com",
        "JIRA_PERSONAL_TOKEN": "your-pat-here"
      }
    }
  }
}

Option 2: Install as a uv tool

# From PyPI
uv tool install www-jira-mcp

# After installation, the command is available globally:
www-jira-mcp

To update or reinstall:

uv tool upgrade www-jira-mcp
# or force reinstall latest:
uv tool install --force www-jira-mcp@latest

Option 3: Run from local source (for development)

git clone https://github.com/naifs/www-jira-mcp.git
cd www-jira-mcp
uv sync
uv run www-jira-mcp

To update:

git pull && uv sync

MCP client config (local source):

{
  "mcpServers": {
    "www-jira-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/www-jira-mcp",
        "www-jira-mcp"
      ],
      "env": {
        "JIRA_URL": "https://jira.example.com",
        "JIRA_PERSONAL_TOKEN": "your-pat-here"
      }
    }
  }
}

Option 4: Install from built wheel

cd /path/to/www-jira-mcp
uv build
uv tool install dist/*.whl

Authentication

The server supports two authentication methods for Jira Server/Data Center:

PAT takes priority if both are configured. JIRA_API_TOKEN is accepted as a legacy fallback for JIRA_PASSWORD.

Environment Variables

Naming pattern: JIRA_FIELD_<FIELDNAME> — use this pattern for custom field overrides (e.g., JIRA_FIELD_TARGET_START for the Target start field).

Resilience

All API requests go through a client-side token-bucket rate limiter and an automatic retry with exponential backoff on 429 / 5xx responses (respects the Retry-After header). Failures are returned to the AI as structured errors with error_code, suggested_action, and retryable hints.

Provided Tools

Read Tools (25)

• jira_search — Search issues using JQL or plain text
• jira_get_issue — Get issue by key or URL
• jira_get_comments — Get issue comments
• jira_get_transitions — Get available status transitions for an issue
• jira_get_projects — List projects
• jira_get_project — Get project by key
• jira_get_link_types — Get available issue link types
• jira_get_attachments — List issue attachments
• jira_download_attachment — Download an attachment by ID to disk (uses attachment metadata API for reliable downloads)
• jira_get_worklogs — Get issue worklogs
• jira_get_watchers — Get issue watchers
• jira_get_priorities — List priorities
• jira_get_statuses — List statuses (globally, or per project via project_key)
• jira_get_resolutions — List resolutions
• jira_get_fields — List fields (system + custom)
• jira_get_issue_types — List issue types (all or per project)
• jira_get_boards — List Agile boards
• jira_get_board — Get board details by ID
• jira_get_sprints — List sprints for a board
• jira_get_sprint — Get sprint details
• jira_get_sprint_issues — Get issues in a sprint
• jira_search_user — Search for users
• jira_get_current_user — Get current authenticated user
• jira_mcp_info — Server configuration guide (env vars, auth status, tool catalog)
• jira_mcp_status — Server status and Jira connectivity check

Write Tools (20) — only when JIRA_READ_ONLY=false

• jira_create_issue — Create a new issue. Use extra_fields for custom fields (dict or JSON string): {"customfield_10101": "EPIC-KEY", "components": [{"name": "..."}]}
• jira_update_issue — Update an existing issue. Use fields parameter with JSON: {"summary": "...", "customfield_12345": value, "components": [{"name": "..."}]}. For Epic Link, use {"customfield_10101": "EPIC-KEY"}
• jira_delete_issue — Delete an issue (⚠️ destructive, requires permissions)
• jira_assign_issue — Assign an issue to a user by username
• jira_add_comment — Add a comment
• jira_update_comment — Update a comment
• jira_delete_comment — Delete a comment
• jira_transition_issue — Transition by ID or name. Before using: call jira_get_transitions() to see available transitions and required fields (e.g., resolution for "Cancel"). Use fields parameter for mandatory fields: {"resolution": {"id": "12345"}}
• jira_sync_issue_dates — Fill Target start/end from sprint dates (epics roll up children). Uses Jira Agile API for reliable epic children discovery. Safety-first: dry_run defaults to true — preview, report the changes to the user, and apply (dry_run=false) only after explicit approval. Set JIRA_FIELD_TARGET_START / JIRA_FIELD_TARGET_END if your Jira uses custom field IDs
• jira_link_issues — Create a link between two issues. Use jira_get_link_types() to find available link types (e.g., "Blocks", "Relates", "Parent")
• jira_delete_link — Delete an issue link
• jira_upload_attachment — Upload a file to an issue
• jira_delete_attachment — Delete an attachment
• jira_add_worklog — Add a worklog entry
• jira_add_watcher — Add a watcher by username
• jira_remove_watcher — Remove a watcher by username
• jira_create_sprint — Create a sprint on a board (requires board_id)
• jira_update_sprint — Update sprint name, goal, dates, or state
• jira_move_issues_to_sprint — Move issues into a sprint (by sprint_id)
• jira_move_issues_to_backlog — Remove issues from sprint to backlog

Multi-User HTTP Mode

By default the server runs over stdio with a single credential set taken from environment variables. Set JIRA_MCP_TRANSPORT=http to serve multiple users over the streamable-HTTP transport:

JIRA_MCP_TRANSPORT=http JIRA_MCP_PORT=8080 uvx www-jira-mcp

In HTTP mode each request may carry its own Jira credentials as headers (same names as the env vars): JIRA_URL, JIRA_PERSONAL_TOKEN, JIRA_USERNAME, JIRA_PASSWORD (or JIRA_API_TOKEN). Per-user HTTP clients are cached for 1 hour. When headers are absent, the server falls back to the environment configuration.

MCP Resources

Resources are read-only reference data that the AI can access by URI — like lightweight cached endpoints. They are useful when the AI needs context (e.g. available priorities, project list) before calling tools.

How it works: When the MCP client connects, it discovers available resources. The AI can then read jira://projects to get the list of projects, for example — without calling jira_get_projects tool. This is useful for providing background context.

When to use Resources vs Tools:

• Resources — for reference data that rarely changes (priorities, statuses, fields). The AI reads them once and uses as context.
• Tools — for actions and dynamic data (search, create issue, get specific issue). Always use tools for anything that depends on parameters.

MCP Prompts

Prompts are reusable templates that pre-fill common workflows. The user invokes a prompt by name with parameters, and gets back a ready-to-use instruction for the AI.

Examples

create_bug prompt:

User invokes: create_bug(summary="Login fails on mobile", steps="1. Open app\n2. Tap Login", expected="Redirect to dashboard", actual="Error 500")

AI receives:

Create a Jira bug with the following details:

Summary: Login fails on mobile
Description:
*Steps to Reproduce:*
1. Open app
2. Tap Login

*Expected Result:*
Redirect to dashboard

*Actual Result:*
Error 500

Use the `jira_create_issue` tool with `issuetype='Bug'`. Optionally set `extra_fields` for custom fields like Epic Link or components.

jql_search prompt:

User invokes: jql_search(project="PROJ", status="In Progress", assignee="me")

AI receives:

Run the following JQL query using the `jira_search` tool:

project = "PROJ" AND status = "In Progress" AND assignee = currentUser()

If the results are too broad, help me refine the query.

daily_standup prompt:

User invokes: daily_standup(project="PROJ")

AI receives:

Generate a daily standup report for me.

1. Run `jira_search` with JQL: `project = "PROJ" AND assignee = currentUser() AND updated >= -1d`
2. Optionally call `jira_get_transitions()` on key issues to see what moved
2. Summarize: what was done, what's in progress, what's blocked.
3. List any issues that transitioned to Done in the last day.

Quick Verification

# Run the server
JIRA_URL=https://jira.example.com JIRA_PERSONAL_TOKEN=your-token \
uv run www-jira-mcp

Troubleshooting

uv not found

Install uv and reopen your terminal. See System Requirements.

Dependencies missing

uv sync

MCP tools not appearing in client

1. Check that the MCP client config JSON is valid.
2. Ensure the --project path is absolute and correct.
3. Reload the MCP client after config changes.
4. Check JIRA_DEBUG=true for detailed logs.

Authentication error

• Verify JIRA_URL points to your Server/DC instance (not *.atlassian.net).
• For PAT: ensure the token is valid and not expired.
• For Basic auth: ensure both JIRA_USERNAME and JIRA_PASSWORD are set.

Wrong project path in config

The --project argument must point to the root directory of www-jira-mcp (where pyproject.toml is located), not to the src/ subdirectory.

License

MIT