jira-full-mcp

A local, Python MCP server for administering Atlassian Cloud (Assets + Jira) from Claude Code. It complements the official plugin:atlassian:atlassian (issues/comments) with capabilities it doesn't have: Assets (schemas / object types / attributes / objects / AQL / bulk import / declarative apply) and Jira admin (projects / issue types / fields / workflows / statuses / screens / permission-notification-priority-security schemes / boards / sprints / epics). Issue CRUD is intentionally NOT covered — use the official plugin:atlassian for that.

Status: v0.2.2 released — 379 MCP tools (Assets + Jira), 2651 unit tests, clean mypy --strict + ruff, live-verified against a real workspace. Phases 1-6 complete. See CHANGELOG.md.

Documentation

Doc	About
CLAUDE.md	Loaded first in a new Claude session — hard rules, quality gates, file map, gotchas
docs/installation.md	Install from source + register in Claude Code + verify
docs/authentication.md	API tokens, two-site setup, 401/403 troubleshooting, permissions
docs/architecture.md	Layers (core/models/api/services/tools), envelope, production guard, how to add a resource
docs/troubleshooting.md	Symptom → cause → fix; rate-limit, 4xx, AQL, multipart, async polling
docs/tools_reference.md	Auto-generated reference of all 379 MCP tools with signatures and docstrings
docs/conventions.md	ADRs (destructive scope, production guard scope, file-path security)
docs/recipes/	Step-by-step Claude Code workflows
CHANGELOG.md	Release history (Keep-a-Changelog)

Quick start

You run the server from a local clone. Six steps:

1. Install prerequisites — Python 3.11+ and uv:

# macOS
brew install uv
# Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone and install dependencies. Pick a permanent folder (NOT inside a project you might delete) — we recommend ~/mcp-servers/:

mkdir -p ~/mcp-servers && cd ~/mcp-servers
git clone https://github.com/denisglazkov/jira-full-mcp.git
cd jira-full-mcp
make install

3. Create an Atlassian API token — use "Create API token" (classic), NOT "with scopes": https://id.atlassian.com/manage-profile/security/api-tokens

4. Add your credentials:

cp .env.example .env

Open .env and fill in the three ASSETS_* values (domain / email / token). For Jira admin features (projects, workflows, boards, …) also fill in the JIRA_* values. Full guide: docs/authentication.md.

5. Register in Claude Code — run this from the clone directory (where you are after step 2). $(pwd) fills in the absolute path for you, so there is nothing to edit by hand:

claude mcp add jira-full-mcp -s user -- uv run --directory "$(pwd)" python -m jira_mcp

-s user makes it available in every project. Verify with claude mcp list.

<details> <summary>Prefer to edit the config by hand? (optional)</summary>

Add this to ~/.claude/settings.json, replacing /absolute/path/to/jira-full-mcp with the clone's absolute path (e.g. /Users/you/mcp-servers/jira-full-mcp) — full path, not ~:

{
  "mcpServers": {
    "jira-full-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/jira-full-mcp", "python", "-m", "jira_mcp"],
      "env": {}
    }
  }
}

</details>

6. Fully restart Claude Code (quit completely — Cmd+Q on macOS — not just close the window). Then run /mcp: you should see jira-full-mcp with ~379 tools.

Full step-by-step walkthrough: docs/installation.md.

Recipes

#	Recipe	What it covers
01	Create schema from scratch	Manual schema with OTs, attrs, references
02	Attribute types cheatsheet	All attribute types with examples
03	Bulk import from CSV	CSV → mapping JSON → 100+ objects
04	Apply declarative SchemaDefinition	Idempotent JSON-driven schemas
05	AQL queries cheatsheet	12 AQL search patterns
06	Clone schema for staging	Back up prod → apply to a staging workspace

Jira admin (Phase 2-6)

All Jira recipes operate only on test resources (project key JMT*, names __test_jiramcp_*); production projects (e.g. MYPROJ) are blocked by the production guard. Each recipe ends with a cleanup step.

#	Recipe	What it covers
07	Jira project bootstrap	Project → components → versions → role actor → property (Phase 2)
08	Custom workflow (draft→publish)	Safe draft→publish flow for an active scheme (Phase 3)
09	Issue types & screens	ITS + screen + screen scheme + ITSS → assign (Phase 2+4)
10	Permission & security schemes	Permission / notification / issue security schemes (Phase 5)
11	Scrum board & sprints	Board + sprint lifecycle create→start→complete (Phase 6, Agile)

Development

make check               # ruff + mypy --strict (on src/)
make test                # unit tests (no network, ~2651 tests)
make test-integration    # requires ASSETS_INTEGRATION_TESTS=1 / JIRA_INTEGRATION_TESTS=1
make serve               # run the MCP server locally (for debugging)

# Auto-generated artefacts
make docs-tools          # regenerate docs/tools_reference.md
make docs-tools-check    # CI: fail if stale

# API coverage
make api-spec-fetch      # download the latest Atlassian Assets OpenAPI
make api-coverage        # check spec vs implementation (≥75% gate)

Pre-commit hooks (ruff format/lint + mypy) are installed once:

uv run pre-commit install

Status

• v0.2.2 — released 2026-06-01. In-schema AQL/JQL syntax cheatsheets in tool descriptions — no new tools. See CHANGELOG.md.
• v0.2.1 — released 2026-06-01. MCP-conformance + safety hardening (tool annotations, server instructions, typed parameter schemas) — no new tools. See CHANGELOG.md.
• v0.2.0 — released 2026-05-30. Phases 1-6 complete. 379 MCP tools, 1775 unit tests. See CHANGELOG.md.
• Phase 1 (Assets): schemas / object types / attributes / objects / AQL / bulk import / declarative apply / backup. ~83 tools.
• Phase 2-6 (Jira admin): projects + issue types + fields (Phase 2) · workflows + statuses + schemes (Phase 3) · screens + ITSS (Phase 4) · permission/notification/priority/issue-security schemes + identity (Phase 5) · boards + sprints + epics (Phase 6). ~296 jira_* tools.
• Safety: the production guard (e.g. MYPROJ, configurable via JIRA_PRODUCTION_PROJECT_KEYS) runs on all scheme/project mutations — server-side, cannot be bypassed via a numeric id; issue CRUD is not covered by design.

Performance

Bulk import / batch operations:

Batch size	Wall-clock	Throughput	p95 latency
100 objects	TBD after the first make benchmark	—	—
500 objects	TBD	—	—
1000 objects	TBD	—	—

Numbers will be filled in after running make benchmark against a real Atlassian Cloud instance. The Atlassian-side rate limit is ≈ 1000 req/min.

Contributing

Issues and PRs welcome via GitHub. Any contribution must:

• Pass make check (ruff + mypy --strict).
• Be covered by unit tests (make test).
• Not violate the MCP stdio invariant (logs to stderr).
• Honor the envelope contract (tools never raise).

License

MIT — see pyproject.toml.