Skip to main content
Glama

Jirum

An MCP server that lets Claude (Desktop or Code) create, search and update Jira Cloud work items as you, using Atlassian OAuth 2.0 (3LO). Works with any Atlassian tenant; each user authorizes with their own Atlassian account and tokens stay on their machine.

Claude Desktop / Claude Code
        │  MCP (stdio)
        ▼
      Jirum    ──── OAuth 2.0 access token ────▶  api.atlassian.com/ex/jira/{cloudId}
        │
        └── ~/.config/jirum/tokens.json (0600, rotating refresh token)

What Claude can do

Area

Tools

Auth

jira_connect, jira_auth_status, jira_list_sites, jira_select_site, jira_disconnect

Discovery

jira_myself, jira_list_projects, jira_get_project, jira_get_issue_types, jira_get_create_fields, jira_get_fields, jira_get_link_types, jira_get_priorities, jira_search_users

Issues

jira_search_issues (JQL), jira_count_issues, jira_get_issue, jira_create_issue, jira_update_issue, jira_assign_issue, jira_get_transitions, jira_transition_issue, jira_add_comment, jira_get_comments, jira_link_issues, jira_delete_issue

Hierarchy

jira_create_epic, jira_create_child_issue (Feature/Story/Task/Bug under an Epic), jira_create_subtask, jira_create_epic_with_children, jira_get_children

Sprints

jira_get_boards, jira_get_sprints, jira_get_sprint_issues, jira_add_to_sprint

Opinionated

jira_search_my_tickets, jira_find_duplicate_ticket, jira_create_ticket_from_context

Descriptions and comments are written in Markdown and converted to Atlassian Document Format (headings, lists, code blocks, tables, links, bold/italic/strike, inline code). Issue descriptions and comments are returned as Markdown.

Your Jira permissions still apply: OAuth scopes never grant more than your Jira user can do.

Related MCP server: Jira MCP

1. Create the Atlassian OAuth app (once per organisation)

Step-by-step with screenshots-level detail and troubleshooting: see GUIDE.md. Short version:

Atlassian's guidance is to ship one OAuth app per integration rather than asking every user to create their own. Whoever owns the integration does this once and shares the client ID/secret with users through your usual secrets channel.

  1. Open the Atlassian Developer Console and choose Create → OAuth 2.0 integration. Name it (e.g. Jirum).

  2. Permissions → Jira API → Add → Configure, then add these scopes:

    • Classic tab: read:jira-user, read:jira-work, write:jira-work

    • Granular tab: read:project:jira

  3. Still on the Granular tab of Jira API (there is no separate Jira Software card), search jira-software and add:

    • read:board-scope:jira-software, read:sprint:jira-software, write:sprint:jira-software, read:issue:jira-software

  4. Authorization → OAuth 2.0 (3LO) → Configure and set the callback URL to exactly:

    http://localhost:8787/oauth/callback
  5. Settings → copy the Client ID and Secret.

  6. Optional but recommended: under Distribution, set the app to Sharing so users outside your Atlassian org can authorize it. Fill the required details (privacy policy URL etc.).

Skip step 3 and remove the Jira Software scopes from JIRA_SCOPES if you do not want sprint/board tools.

2. Install

git clone https://github.com/RakshitRabugotra/jirum.git
cd jirum
pnpm install
pnpm build

Provide the credentials either as environment variables (set them in the Claude config below) or in ~/.config/jirum/config.json:

{ "clientId": "…", "clientSecret": "…" }

See .env.example for all options (JIRA_OAUTH_REDIRECT_URI, JIRA_SCOPES, JIRA_DEFAULT_SITE, JIRUM_CONFIG_DIR).

3. Authorize

Either from the terminal:

ATLASSIAN_CLIENT_ID=… ATLASSIAN_CLIENT_SECRET=… node dist/index.js login

or later from Claude by asking it to "connect Jira" (it calls jira_connect, which opens the browser and returns the authorization URL). Approve the consent screen; the browser tab says "Jira is connected". If you take longer than the tool's wait, the login keeps waiting in the background for up to 5 minutes and Claude can confirm with jira_auth_status.

If your account can access several Jira sites, pick one:

node dist/index.js sites
node dist/index.js select acme

Other CLI commands: status, logout, config.

4. Connect to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) and add the server (see claude_desktop_config.example.json):

{
  "mcpServers": {
    "jirum": {
      "command": "node",
      "args": ["/absolute/path/to/jirum/dist/index.js"],
      "env": {
        "ATLASSIAN_CLIENT_ID": "…",
        "ATLASSIAN_CLIENT_SECRET": "…"
      }
    }
  }
}

Restart Claude Desktop. Use the full path to node (which node) if Claude cannot find it, since GUI apps do not load your shell profile.

5. Connect to Claude Code

claude mcp add jirum -s user -e ATLASSIAN_CLIENT_ID=… -e ATLASSIAN_CLIENT_SECRET=… -- node /absolute/path/to/jirum/dist/index.js

Both clients share the same token file, so you only authorize once per machine.

Example prompts

  • "Create a Jira ticket in THEOS for the Vite 9 migration, assign it to me, add the acceptance criteria we discussed."

  • "Is there already a ticket about PostgreSQL schema permissions in THEOS?"

  • "Create an epic 'Billing v2' with features 'Invoices' and 'Refunds', each with sub-tasks for API and UI."

  • "Move THEOS-42 to In Progress and comment that the PR is up."

  • "What's in the active sprint for THEOS that's assigned to me?"

  • "Link THEOS-51 as blocked by THEOS-49."

How it works

  • OAuth: authorization-code flow with offline_access. A throwaway HTTP server listens on the callback port only while a login is in progress. Atlassian rotates refresh tokens; the new one is persisted after every refresh. Concurrent tool calls share a single refresh.

  • Multi-site: after login the server stores every accessible site from accessible-resources. Every tool accepts an optional site argument; otherwise the selected site (or JIRA_DEFAULT_SITE) is used.

  • Name resolution: issue types, users (name/email/"me"), priorities, link-type phrases ("is blocked by"), custom fields (by name) and sprints ("active", "next", a name) are resolved to ids server-side so Claude does not have to.

  • Errors come back as readable tool errors (NOT_CONNECTED: …, Jira 403 … missing a scope) so Claude can recover, for example by calling jira_connect.

  • Nothing is written to stdout except MCP protocol messages; logs go to stderr.

Development

pnpm dev            # run from source via tsx
pnpm typecheck
pnpm test:adf       # markdown -> ADF conversion checks

Security notes

  • Tokens are stored in ~/.config/jirum/tokens.json with mode 0600. Delete it (or run jirum logout) to disconnect this machine; revoke the app at https://id.atlassian.com/manage-profile/apps to revoke entirely.

  • Atlassian 3LO does not support PKCE, so the client secret is required for token exchange. Treat it like any other shared app secret.

  • jira_delete_issue is the only destructive tool; it is annotated as such so clients can require confirmation.

Available Tools

38 tools
jira_add_commentAdd commentB

Adds a comment (Markdown) to an issue as the connected user.

Inputs: body (required), issueKey (required), site.

jira_add_to_sprintAdd issues to sprintA

Moves up to 50 issues into a sprint. sprint is an id, a name, 'active' or 'next' (name/active/next need boardId or projectKey; projectKey defaults to the first issue's project).

Inputs: sprint (required), issueKeys (required), site, boardId, +1 more.

jira_assign_issueAssign issueA
Idempotent

Assigns an issue to a user ('me', accountId, email or display name). Omit assignee or pass null/'unassigned' to unassign.

Inputs: issueKey (required), site, assignee.

jira_auth_statusJira connection statusA
Read-only

Shows whether Jira is connected, which Atlassian account is in use, the accessible sites and which one is selected. Call this first if any other tool reports NOT_CONNECTED.

Inputs: no named parameters.

jira_connectConnect Jira (OAuth login)A

Starts the Atlassian OAuth 2.0 login: opens the system browser for consent and returns the authorization URL. Waits up to waitSeconds for the user to approve; if they have not yet, the login keeps waiting in the background (5 minutes total) and you can call this tool again or jira_auth_status to check. Show the user the URL if the browser did not open.

Inputs: force, waitSeconds.

jira_count_issuesCount issues (JQL)A
Read-only

Approximate count of issues matching a JQL query, without fetching them.

Inputs: jql (required), site.

jira_create_child_issueCreate issue under an epicA

Creates a Feature, Story, Task or Bug under a parent Epic (parentKey). The project is taken from the parent. Use issueType='Feature' where the project has that type; call jira_get_issue_types if unsure.

Inputs: summary (required), issueType (required), parentKey (required), site, +8 more.

jira_create_epicCreate epicB

Creates an Epic (the project's epic-level issue type is detected automatically). Then use jira_create_child_issue to add features/stories under it.

Inputs: summary (required), projectKey (required), site, labels, +7 more.

jira_create_epic_with_childrenCreate epic with child issuesA

Creates an Epic and a batch of child issues (features/stories/tasks) under it, optionally with sub-tasks under each child, in one call. Fails fast on the first error and reports what was created.

Inputs: epic (required), children (required), projectKey (required), site.

jira_create_issueCreate issueA

Creates an issue of any type. For hierarchy use parentKey: stories/features/tasks under an Epic, or sub-tasks under a standard issue (jira_create_subtask picks the sub-task type for you). Description is Markdown. Returns the new key and URL.

Inputs: summary (required), issueType (required), projectKey (required), site, +10 more.

jira_create_subtaskCreate sub-taskB

Creates a sub-task under a standard issue (Feature, Story, Task, Bug). The sub-task issue type is detected automatically.

Inputs: summary (required), parentKey (required), site, labels, +7 more.

jira_create_ticket_from_contextCreate ticket from structured contextA

Creates a well-structured ticket from what was discussed: problem statement, context, reproduction steps, expected/actual behaviour, acceptance criteria, technical notes and links. Builds a consistently formatted description. Use jira_find_duplicate_ticket first when appropriate.

Inputs: problem (required), summary (required), issueType (required), projectKey (required), +17 more.

jira_delete_issueDelete issueA
Destructive

Permanently deletes an issue. Irreversible; confirm with the user first.

Inputs: issueKey (required), site, deleteSubtasks.

jira_disconnectDisconnect JiraA
Destructive

Deletes the stored tokens so this machine is no longer authorized. Revoke the app at https://id.atlassian.com/manage-profile/apps to fully revoke access.

Inputs: no named parameters.

jira_find_duplicate_ticketFind possible duplicate ticketsA
Read-only

Before creating a ticket, searches a project for existing issues matching a summary/keywords (text search on summary, description and comments). Returns likely duplicates so the user can decide whether to create a new one.

Inputs: query (required), projectKey (required), site, issueType, +2 more.

jira_get_boardsList boardsB
Read-only

Scrum/Kanban boards, optionally filtered by project key or name. Board ids are needed for sprint lookups.

Inputs: name, site, type, projectKey.

jira_get_childrenGet child issuesA
Read-only

Lists the direct children of an Epic (its features/stories/tasks) or the sub-tasks of a standard issue, with status and assignee.

Inputs: issueKey (required), site, includeDone.

jira_get_commentsGet commentsB
Read-only

Latest comments on an issue, newest first, as Markdown.

Inputs: issueKey (required), site, maxResults.

jira_get_create_fieldsGet fields for creating an issueA
Read-only

Lists the fields (required and optional, with allowed values) for creating an issue of a given type in a project. Use when a create fails because of a missing required field, or to find custom field ids.

Inputs: issueType (required), projectKey (required), site, requiredOnly.

jira_get_fieldsList fieldsA
Read-only

All fields on the site (system and custom) with ids, plus the detected Sprint / Story Points field ids. Filter with query.

Inputs: site, query.

jira_get_issueGet issueA
Read-only

Full details of one issue: fields, description (as Markdown), parent, sub-tasks, links, and optionally recent comments.

Inputs: issueKey (required), site, fields, includeComments.

jira_get_issue_typesGet issue typesA
Read-only

Issue types available in a project (Epic, Feature, Story, Task, Bug, Sub-task...). hierarchyLevel: 1 = epic level, 0 = standard, -1 = sub-task.

Inputs: projectKey (required), site.

jira_get_prioritiesList prioritiesB
Read-only

Priority names available on the site.

Inputs: site.

jira_get_projectGet projectA
Read-only

Project details including its issue types (with hierarchy level and whether each is a sub-task type). Call before creating issues in an unfamiliar project.

Inputs: projectKey (required), site.

jira_get_sprint_issuesGet sprint issuesA
Read-only

Issues in a sprint. sprint is an id, a name, 'active' or 'next' (the latter two need boardId or projectKey).

Inputs: sprint (required), jql, site, boardId, +2 more.

jira_get_sprintsList sprintsA
Read-only

Sprints for a board (by boardId) or for a project's scrum boards (by projectKey). Default state filter: active and future.

Inputs: site, state, boardId, projectKey.

jira_get_transitionsGet available transitionsA
Read-only

Workflow transitions currently available for an issue (name, target status, required fields). Use before jira_transition_issue if unsure of the names.

Inputs: issueKey (required), site.

jira_list_projectsList projectsA
Read-only

Lists Jira projects on the site, optionally filtered by a name/key substring.

Inputs: site, query, maxResults.

jira_list_sitesList accessible Jira sitesA
Read-only

Lists the Jira Cloud sites this account can use through this integration. Re-fetches from Atlassian.

Inputs: no named parameters.

jira_myselfWho am I in JiraA
Read-only

Returns the Atlassian account the integration acts as (accountId, name, email).

Inputs: site.

jira_search_issuesSearch issues (JQL)A
Read-only

Runs a JQL query and returns a compact list. Examples: 'project = THEOS AND statusCategory != Done ORDER BY updated DESC', 'assignee = currentUser() AND sprint in openSprints()', 'text ~ "vite migration"'. Use nextPageToken to continue.

Inputs: jql (required), site, fields, format, +2 more.

jira_search_my_ticketsMy ticketsA
Read-only

Issues assigned to the connected user, newest activity first. Defaults to open issues only. Filter by project, status category, or recent updates.

Inputs: site, status, maxResults, projectKey, +2 more.

jira_search_usersSearch usersA
Read-only

Finds Jira users by name or email. Pass projectKey to restrict to users assignable in that project. Returns accountIds for use as assignee.

Inputs: query (required), site, maxResults, projectKey.

jira_select_siteSelect Jira siteA

Chooses the default Jira site for all tools (by cloud id, name, or URL). Persists across restarts.

Inputs: site (required).

jira_transition_issueTransition issue (change status)A

Moves an issue through its workflow. transition can be the transition name, the target status name (e.g. 'In Progress', 'Done'), or the transition id. Optionally adds a comment or sets a resolution.

Inputs: issueKey (required), transition (required), site, fields, +2 more.

jira_update_issueUpdate issueA
Idempotent

Updates fields on an issue. Only provided fields change. labels replaces the whole set; use addLabels/removeLabels for incremental changes. Set parentKey to move an issue under a different Epic, or null to detach.

Inputs: issueKey (required), site, labels, dueDate, +12 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 38 tools

    Disambiguation3/5

    The read/lookup tools are well separated, but the create surface has heavy overlap: jira_create_issue can do anything jira_create_epic, jira_create_child_issue, jira_create_subtask, and jira_create_ticket_from_context do, and jira_get_fields / jira_get_create_fields / jira_get_issue_types all answer 'what fields do I need?'. Descriptions do explain when to prefer each, which keeps this from being worse than moderate ambiguity.

    Naming Consistency4/5

    Nearly everything follows a jira_verb_noun snake_case pattern (jira_get_issue, jira_list_projects, jira_add_to_sprint), making the set easy to scan. A few stragglers drop the noun or use noun-only forms (jira_myself, jira_connect, jira_disconnect, jira_auth_status), but they are few and readable.

    Tool Count2/5

    38 tools is heavy even for Jira's breadth, and several are convenience composites that duplicate existing primitives (jira_create_epic_with_children, jira_create_ticket_from_context, jira_find_duplicate_ticket, jira_count_issues). The surface could be trimmed substantially without losing capability.

    Completeness4/5

    Core workflows are well covered: JQL search, issue CRUD, hierarchy creation, transitions, assignment, links, comments (create/read), boards, sprints, and sprint membership. Gaps remain around attachments, worklogs, watchers, changelog, and deleting/updating comments or links, which agents cannot work around for those tasks.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Connects Jira with Claude, enabling users to search issues, view issue details, update issues, add comments, and retrieve project information through natural language commands.
      1
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Jira Cloud instances, including creating and updating issues, managing sprints and projects, adding comments, tracking worklogs, and searching with presets.
      4 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude AI to interact with JIRA for project management and issue tracking, supporting JQL queries, comprehensive issue details retrieval with subtasks and linked issues, and release planning analysis.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants like Claude to interact with Jira for project management tasks, including issue creation, updates, workflow transitions, and bulk operations.
      4
      MIT