Jira Admin MCP Server

Jira Admin MCP Server

A Model Context Protocol server that gives an AI assistant (Claude, Cursor, VS Code, or any MCP client) 78 purpose-built tools to administer a Jira Cloud site - not just read and create tickets, but the behind-the-scenes admin work: custom fields and where they appear, permission schemes, workflows, screens, issue-type schemes, groups, project roles, saved filters, and bulk operations.

Most Jira MCP servers cover everyday usage. This one covers administration, and adds safety rails (dry-run mode, shared-scheme detection, identity checks before group changes, actionable errors) so an agent can run real admin jobs end to end.

Built with FastMCP. Talks to the Jira Cloud REST API v3 with your own Atlassian email + API token.

---

Quick start

Two prerequisites, both one-time and quick:

1. An Atlassian API token (it inherits your Jira permissions, so use an account with the access you need): create one here.
2. uv installed (one line; it manages Python and dependencies for you, no virtualenv).

Then add the server with the one-click button or one-line command for your tool, and fill in your three JIRA_* values.

Cursor

Click the button, confirm in Cursor, then open ~/.cursor/mcp.json (or Cursor Settings -> MCP) and set JIRA_BASE_URL, JIRA_EMAIL, and JIRA_API_TOKEN on the jira-admin entry.

Claude Code

One command (swap in your own three values):

claude mcp add --scope user \
  --env JIRA_BASE_URL=https://your-company.atlassian.net \
  --env JIRA_EMAIL=you@your-company.com \
  --env JIRA_API_TOKEN=your_api_token_here \
  --transport stdio jira-admin \
  -- uvx jira-admin-mcp

--scope user makes it available in every project; drop it to add only to the current one. Check with claude mcp list.

VS Code

After installing, set your JIRA_* values on the jira-admin entry in .vscode/mcp.json (or your user mcp.json).

Any other MCP client (manual)

Add this block to the client's MCP config:

{
  "mcpServers": {
    "jira-admin": {
      "command": "uvx",
      "args": ["jira-admin-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "you@your-company.com",
        "JIRA_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Want the unreleased main instead of the PyPI release? Replace "args": ["jira-admin-mcp"] with "args": ["--from", "git+https://github.com/its-qusai-nasr/jira-admin-mcp", "jira-mcp"].

Config file locations: Claude Desktop claude_desktop_config.json (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\); Cursor ~/.cursor/mcp.json; VS Code .vscode/mcp.json (note: VS Code uses a top-level "servers" key instead of "mcpServers"). Restart the client after editing; the server appears as jira-admin with all 78 tools.

Local clone (for development)

git clone https://github.com/its-qusai-nasr/jira-admin-mcp
cd jira-admin-mcp
uv sync                 # creates .venv and installs deps from uv.lock
cp .env.example .env    # then edit .env with your Jira credentials
uv run jira-mcp         # starts the server over stdio

---

Configuration

The server reads its settings from environment variables (passed via the env block above, or from a .env file in the project directory when you run a local clone).

Tip: set JIRA_DRY_RUN=true for your first session. Every write tool will return a {"dry_run": true, "would_call": ...} preview so you can watch what the agent intends to do before letting it touch live data.

---

What you can ask for

Once connected, the assistant can do things like:

• "Add alice@example.com to the jira-developers group."
• "Scope the Team custom field to projects ENG and OPS only, for the Story and Bug issue types."
• "Which projects share permission scheme 10789? I want to edit it without breaking the others."
• "Move every Internal Task in project OPS to the Task type, then transition the open ones to In Progress."
• "Create a saved filter for unresolved bugs assigned to me and share it with the developers group."
• "Show me the change history for PROJ-123 and tell me who reopened it."

---

Tools (78 total)

---

Design notes

• Consolidate, don't wrap - 78 workflow-oriented tools rather than a 1:1 mirror of every REST endpoint.
• Dry run - JIRA_DRY_RUN=true makes all write ops return simulated payloads.
• Response filtering - strips self, _links, avatarUrls, and similar noise so the agent sees only useful fields.
• Detail levels - read tools take detail="summary" (default) or detail="full".
• ADF auto-wrap - plain text in comments/descriptions is auto-converted to Atlassian Document Format.
• Transition resolution - jira_issues_transition resolves a status name to its transition ID automatically.
• Actionable errors - error messages say what went wrong and what to try next.
• Token-auth scope - webhook endpoints (/webhook) are intentionally not wrapped; Atlassian restricts them to Connect / OAuth 2.0 apps that token auth cannot satisfy.

---

Testing locally

Inspect and call tools interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector uvx --from . jira-mcp

Run the unit tests (no network calls):

uv sync --extra dev
uv run pytest
uv run ruff check .

---

Security

• Never commit credentials. .env is gitignored; use the env block in your client config or your OS secret manager.
• Least privilege. The API token acts as your Jira user. Use an account scoped to only what you need, especially for write/admin tools.
• Start in dry-run. JIRA_DRY_RUN=true lets you review every intended write before going live.
• See the official MCP security best practices.

---

Contributing

Issues and PRs welcome. See CONTRIBUTING.md.

License

MIT