www-jira-mcp 1.0.0

MCP server providing Jira Server/Data Center integration: issue management, search, projects, and more.

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 50 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

Requirement	Version
uv	Install guide
Python	3.10+ (managed automatically by uv)
Jira	Server 7.0+ / Data Center 8.0+

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:

Method	Environment Variables
Personal Access Token (PAT) (recommended)	JIRA_PERSONAL_TOKEN
Basic Auth (username + password)	JIRA_USERNAME + JIRA_PASSWORD

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

Environment Variables

Variable	Description	Default
JIRA_URL	Jira Server/DC base URL (required)	—
JIRA_PERSONAL_TOKEN	Personal Access Token for PAT auth	—
JIRA_USERNAME	Username for Basic auth	—
JIRA_PASSWORD	Password for Basic auth	—
JIRA_SSL_VERIFY	Verify SSL certificates	true
JIRA_TIMEOUT	HTTP request timeout in seconds	30
JIRA_MAX_RESULTS	Default max results per query (1..100)	50
JIRA_READ_ONLY	Disable write tools (true/false)	true
JIRA_PROJECTS_FILTER	Comma-separated project keys to filter searches	—
JIRA_HTTP_PROXY	HTTP proxy URL	—
JIRA_HTTPS_PROXY	HTTPS proxy URL	—
JIRA_DEBUG	Enable debug logging (1/true/yes/on)	false

Provided Tools

Read Tools (24)

• 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_project_statuses — Get statuses for a project
• jira_get_link_types — Get available issue link types
• jira_get_attachments — List issue attachments
• jira_download_attachment — Download a single attachment
• jira_get_worklogs — Get issue worklogs
• jira_get_watchers — Get issue watchers
• jira_get_priorities — List priorities
• jira_get_statuses — List statuses
• 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

Write Tools (18) — only when JIRA_READ_ONLY=false

• jira_create_issue — Create a new issue
• jira_update_issue — Update an existing issue
• jira_delete_issue — Delete an issue
• jira_assign_issue — Assign an issue to a user
• jira_add_comment — Add a comment
• jira_update_comment — Update a comment
• jira_delete_comment — Delete a comment
• jira_transition_issue — Transition by ID
• jira_transition_issue_by_name — Transition by name (e.g. "Done", "In Progress")
• jira_link_issues — Create a link between two issues
• 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
• jira_remove_watcher — Remove a watcher
• jira_create_sprint — Create a sprint
• jira_update_sprint — Update sprint fields
• jira_move_issues_to_sprint — Move issues into a sprint
• jira_move_issues_to_backlog — Move issues to backlog

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.

URI	Description	Example Output
jira://projects	List of projects	PROJ: My Project
jira://issuetypes	Issue types (incl. sub-tasks)	Bug: A problem...
jira://priorities	Priority levels	High: Major...
jira://statuses	Statuses with categories	In Progress [In Progress]: ...
jira://fields	System + custom fields	summary — Summary [string]

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.

Prompt	Parameters	Description
create_bug	summary, steps, expected, actual	Structured bug report template
jql_search	project, status, assignee, priority, issuetype	JQL query builder
daily_standup	project, assignee	Daily standup report generator

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'.

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. 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