Metadata-Version: 2.4
Name: www-jira-mcp
Version: 1.0.1
Summary: MCP server providing Jira Server/Data Center integration: issue management, search, projects, and more.
Project-URL: Homepage, https://github.com/naifs/www-jira-mcp
Project-URL: Repository, https://github.com/naifs/www-jira-mcp
Project-URL: Issues, https://github.com/naifs/www-jira-mcp/issues
Author-email: Naifs <naifs.rage@gmail.com>
License: MIT
License-File: LICENSE
Keywords: atlassian,issue-tracker,jira,mcp,www-jira-mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Bug Tracking
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.26.0
Requires-Dist: truststore>=0.10.4
Description-Content-Type: text/markdown

# 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](https://docs.astral.sh/uv/getting-started/installation/) |
| **Python** | 3.10+ (managed automatically by `uv`) |
| **Jira** | Server 7.0+ / Data Center 8.0+ |

### Install uv

**macOS / Linux:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows (PowerShell):**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**macOS (Homebrew):**
```bash
brew install uv
```

## Installation

### Option 1: Run directly with `uvx` (recommended)

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

```bash
uvx www-jira-mcp
```

MCP client config:

```json
{
  "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`

```bash
# From PyPI
uv tool install www-jira-mcp

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

To update or reinstall:

```bash
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)

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

To update:

```bash
git pull && uv sync
```

MCP client config (local source):

```json
{
  "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

```bash
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 TLS certificates (system trust store via `truststore`) | `true` |
| `JIRA_SSL_PATH` | Optional path to extra CA certs (PEM file or OpenSSL-hashed dir), loaded **in addition to** the system trust store | — |
| `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

```bash
# 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](#system-requirements).

### Dependencies missing
```bash
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
