Metadata-Version: 2.4
Name: ff-mcp-jira
Version: 1.1.0
Summary: Reliable Jira MCP server (Server/DC & Atlassian Cloud), no Node.js — runs on Python via uv. 37 tools: issues, labels, transitions, comments, worklog, links, remote links, watchers, attachments, user/assignable search, field & create metadata, agile boards/sprints.
Project-URL: Homepage, https://github.com/AlexWolfGoncharov/ff-mcp-jira
Author-email: Oleksandr Honcharov <oleksandr.honcharov@fintech-farm.com>
License-Expression: MIT
Keywords: anthropic,atlassian,claude,jira,jira-cloud,jira-data-center,jira-server,mcp,model-context-protocol
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2.0
Description-Content-Type: text/markdown

# ff-mcp-jira (Python / uv)

The same reliable Jira MCP server as [`ff-mcp-jira`](../mcp-jira), but **no Node.js**.
One Python file, run by [`uv`](https://docs.astral.sh/uv/). `uv` downloads its own
Python and dependencies on first run — colleagues only need `uv` installed.

Same 37 `jira_*` tools, same behavior: Jira Server / Data Center (Bearer PAT) and
Atlassian Cloud (Basic + ADF) auto-detected, retries, timeouts, lean fields, full
error bodies surfaced to the model.

## 1. Install uv (one time)

**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"
```

## 2. Get `server.py`

Copy `server.py` to a folder you'll keep, e.g. `~/mcp-jira-py/server.py`
(Windows: `C:\Users\you\mcp-jira-py\server.py`).

## 3. Warm the cache once (avoids a client startup timeout)

The very first run downloads Python + deps (~10–20s). Do it once from a terminal so
your MCP client doesn't time out on first launch:

```bash
uv run --python 3.12 --script /ABSOLUTE/PATH/server.py
```
It will print `Starting ff-mcp-jira` and wait — press Ctrl-C, it's working.

## 4. Configure your MCP client

Claude Desktop config — macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`,
Windows: `%APPDATA%\Claude\claude_desktop_config.json`. (Claude Code: `claude mcp add` or its config.)

**macOS / Linux:**
```json
{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": ["run", "--python", "3.12", "--script", "/Users/you/mcp-jira-py/server.py"],
      "env": {
        "JIRA_BASE_URL": "https://jira.fintech-farm.com",
        "JIRA_API_TOKEN": "your-personal-access-token"
      }
    }
  }
}
```

**Windows:**
```json
{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": ["run", "--python", "3.12", "--script", "C:\\Users\\you\\mcp-jira-py\\server.py"],
      "env": {
        "JIRA_BASE_URL": "https://jira.fintech-farm.com",
        "JIRA_API_TOKEN": "your-personal-access-token"
      }
    }
  }
}
```

> If `uv` isn't found, use its full path (`which uv` / `where uv`), e.g.
> macOS `/Users/you/.local/bin/uv`, Windows `C:\\Users\\you\\.local\\bin\\uv.exe`.
> `--python 3.12` makes `uv` provision a Python even on machines that have none.

Restart the client — the `jira_*` tools appear in the next conversation.
First smoke test: ask it to call `jira_get_myself`.

## Auth

| Deployment | `JIRA_API_TOKEN` is | `JIRA_USERNAME` / `JIRA_EMAIL` |
| --- | --- | --- |
| **Jira Server / Data Center** | Personal Access Token (profile → Personal Access Tokens) | Optional, ignored for auth |
| **Atlassian Cloud** (`*.atlassian.net`) | API token from id.atlassian.com → API tokens | Required (your account email) |

Auto-detected from the hostname. Force with `JIRA_AUTH_MODE=basic|bearer`.

## Self-check

```bash
uv run --python 3.12 --script smoke.py
```
Boots the server offline, asserts all 37 tools register and the ADF/auth/clamp/URL
logic is correct. No network calls.
