jira-issue-context-mcp

Read-only MCP server that gives Codex, Claude, Cursor, or any MCP client Jira issue context and JQL-based task discovery.

It intentionally stays narrow: fetch a single issue by key or list issues from a JQL query without performing Jira writes.

Features

• Self-describing helper tool: jira_issue_help

• Issue context read-only tool: jira_issue_context

• Workflow/router triage read-only tool: jira_issue_workflow

• JQL read-only task discovery tool: jira_issue_search

• No board listing, sprint browsing, transitions, comment creation, or writes

• Converts Jira ADF descriptions/comments into plain Markdown-ish text

• Paginates all issue comments

• Validates JQL before search by default

• Reads available transitions, issue links, subtasks, and recent changelog for router triage

• Returns image attachments as MCP image content

• Supports Atlassian Cloud API token auth, bearer auth, or browser/session cookie auth

• Optional Playwright login helper for cookie-based SSO setups

Related MCP server: Work Integrations MCP

Tools

jira_issue_help

Explains what tools this MCP exposes, when to use each one, and example arguments. It does not call Jira and does not require Jira authentication.

Inputs:

• topic: optional help topic. Supported values: overview, router, config, jira_issue_search, jira_issue_workflow, jira_issue_context.

Use this tool when the model is unsure whether it should search by JQL, triage workflow state, or fetch full issue context.

jira_issue_context

Fetches the context for one issue key: title, description, comments, attachment summary, and image attachments.

jira_issue_workflow

Fetches a read-only workflow view for one issue key so routers can decide whether to create agent work.

Inputs:

• issueKey: Jira issue key. Optional if the MCP was started with --issue=KEY or JIRA_ISSUE_KEY.

• maxChangelogEntries: maximum recent changelog entries to return. Defaults to 5, maximum 20.

The output includes:

• current status and status category

• available transitions for the authenticated user

• subtasks and their statuses

• issue links and linked issue statuses

• recent changelog entries

• a stable Router Payload JSON block with taskKey, routerAction, availableTransitions, and workflow signals

Possible routerAction values:

• ready_for_agent_work: issue is not done and transitions are available

• review_no_available_transitions: issue is not done, but Jira returned no transitions for this user/status

• skip_done: issue is already in a Done status category

jira_issue_search

Runs a read-only JQL query and returns a compact task list for routers plus issue metadata.

Inputs:

• jql: JQL query to execute.

• maxIssues: maximum issues to return. Defaults to JIRA_DEFAULT_JQL_MAX_ISSUES or 5, maximum 200.

• validateJql: validates the JQL before searching. Defaults to true.

The output includes a stable Router Payload JSON block with taskKeys, issueCount, limit, and isTruncated. If isTruncated is true, the JQL matched more issues than maxIssues.

Example Router Payload:

{
  "taskKeys": ["XXXX-123", "XXXX-345"],
  "issueCount": 2,
  "limit": 5,
  "isTruncated": false
}

Example router prompt:

Actua como router. Ejecuta este JQL y trabaja en las tareas en paralelo:

project = XXXX AND statusCategory != Done ORDER BY priority DESC, updated ASC

Primero usa jira_issue_search para obtener las claves. Despues delega a jira-pm para
revisar cada issue con jira_issue_workflow. Si routerAction es ready_for_agent_work,
recoge contexto por issue con jira_issue_context y crea una conversacion por tarea.
No trabajes mas de 5 issues por ejecucion salvo que yo indique otro maxIssues.

For a daily Codex automation, use the same router prompt and keep maxIssues low. The MCP only discovers and reads Jira issues; branch creation, worktrees, delegation, commits, and pull requests belong to the Codex router/agents that consume the returned task keys.

Install

npm install
npm run build

Development

Run the full local validation:

npm test

The test suite builds TypeScript and runs Node's built-in test runner. Current coverage includes:

• config loading, auth selection, numeric defaults, and issue key validation

• Jira issue field requests and HTTP error reporting

• ADF-to-text conversion

• image attachment download/skip behavior

• JQL search pagination, truncation, and validation

• helper guidance topics and examples

• stable router payload formatting

• workflow triage payloads, transitions, links, subtasks, and changelog formatting

Authentication

Set JIRA_BASE_URL plus one auth method.

Optional safety limit for JQL task discovery:

JIRA_DEFAULT_JQL_MAX_ISSUES=5

You can put these variables in the shell environment or in a .env file in the directory where the MCP command is started. The package also checks its own local .env as a fallback.

If your MCP client starts the server from a different working directory, pass --env-file or set JIRA_ENV_PATH so the server reads the intended project .env explicitly:

JIRA_ENV_PATH=/absolute/path/to/your/project/.env

jira-issue-mcp --env-file=/absolute/path/to/your/project/.env

For Codex project config, prefer --env-file in args because it avoids relying on the parent Codex process environment.

Recommended for Atlassian Cloud:

JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=you@example.com
JIRA_API_TOKEN=your-atlassian-api-token

Bearer token:

JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_BEARER_TOKEN=your-token

Cookie/session token:

JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_SESSION_TOKEN=your-cookie-value
JIRA_COOKIE_NAME=tenant.session.token

For SSO environments where API tokens are not available, the login helper can capture a browser cookie:

npx -y --package github:formonkey/jira-issue-context-mcp#main jira-issue-login \
  --base-url=https://your-domain.atlassian.net \
  --cookie-name=tenant.session.token \
  --storage-state=.auth/jira-storage-state.json

Run it from your project root. The first successful run writes JIRA_SESSION_TOKEN to .env and saves Playwright auth state to .auth/jira-storage-state.json. Later runs try that stored auth state first, refresh .env, and only open the browser again if the state is missing or expired.

--force-login=false is the normal mode. It does not disable login. It means:

1. Try the stored Playwright state first.

2. If the stored state is still valid, write a fresh JIRA_SESSION_TOKEN to .env and exit.

3. If the stored state is missing or expired, open the login browser, let the user complete SSO, capture the cookie, and update .env.

Use --force-login=true only when you explicitly want to ignore the stored state and force a fresh browser login.

If your Atlassian organization only shows SSO from a specific Jira application login URL, pass it explicitly:

npx -y --package github:formonkey/jira-issue-context-mcp#main jira-issue-login \
  --base-url=https://your-domain.atlassian.net \
  --cookie-name=tenant.session.token \
  --login-url="https://id.atlassian.com/login?...&application=jira&orgId=..."

Or let the helper build the Atlassian login URL:

npx -y --package github:formonkey/jira-issue-context-mcp#main jira-issue-login \
  --base-url=https://your-domain.atlassian.net \
  --cookie-name=tenant.session.token \
  --atlassian-site-id=your-site-id \
  --atlassian-org-id=your-org-id \
  --login-application=jira \
  --login-continue=https://your-domain.atlassian.net/browse/PROJ-123

If Microsoft SSO blocks the automated browser, start Edge yourself with remote debugging and let the helper connect to that real Edge session:

npx -y --package github:formonkey/jira-issue-context-mcp#main jira-issue-login \
  --base-url=https://your-domain.atlassian.net \
  --cookie-name=tenant.session.token \
  --launch-browser=msedge \
  --cdp-port=9222 \
  --default-profile=true \
  --close-existing-browser=true

This closes existing Edge processes, launches a real Edge process with the installed browser's default profile, connects to it over CDP, waits for you to finish Microsoft SSO, captures the Jira session cookie, and writes it to .env.

Advanced manual mode:

start msedge --remote-debugging-port=9222

Then run:

npx -y --package github:formonkey/jira-issue-context-mcp#main jira-issue-login \
  --base-url=https://your-domain.atlassian.net \
  --cookie-name=tenant.session.token \
  --cdp-url=http://127.0.0.1:9222

Both CDP modes are useful for corporate SSO because the browser is launched as a normal installed browser instead of a Playwright-managed browser.

Recommended Project Makefile

For project usage, wrap the long login command in make. The important commands are:

make jira-login
make jira-check

make jira-login should be the single normal login command. It tries the stored auth state first and only opens the SSO browser when required.

make jira-check should verify that the generated .env contains a valid Jira session before starting Codex or another MCP client.

Example for a project that vendors this MCP under mcps/jira:

JIRA_BASE_URL ?= https://your-domain.atlassian.net
JIRA_COOKIE_NAME ?= tenant.session.token
JIRA_STORAGE_STATE ?= .auth/jira-storage-state.json
JIRA_FORCE_LOGIN ?= false
JIRA_LOGIN_URL ?= https://id.atlassian.com/login?...&application=jira&orgId=...

.PHONY: jira-build jira-install-browser jira-login jira-check
jira-build: ; npm --prefix mcps/jira run build
jira-install-browser: ; npm --prefix mcps/jira exec playwright install chromium
jira-login: ; node mcps/jira/dist/login-cli.js --base-url="$(JIRA_BASE_URL)" --cookie-name="$(JIRA_COOKIE_NAME)" --storage-state="$(JIRA_STORAGE_STATE)" --login-url="$(JIRA_LOGIN_URL)" --force-login="$(JIRA_FORCE_LOGIN)"
jira-check: ; node mcps/jira/dist/check-cli.js

Equivalent make jira-login command when using the package directly from GitHub:

JIRA_BASE_URL ?= https://your-domain.atlassian.net
JIRA_COOKIE_NAME ?= tenant.session.token
JIRA_STORAGE_STATE ?= .auth/jira-storage-state.json
JIRA_FORCE_LOGIN ?= false
JIRA_LOGIN_URL ?= https://id.atlassian.com/login?...&application=jira&orgId=...

.PHONY: jira-login jira-check
jira-login: ; npx -y --package github:formonkey/jira-issue-context-mcp#main jira-issue-login --base-url="$(JIRA_BASE_URL)" --cookie-name="$(JIRA_COOKIE_NAME)" --storage-state="$(JIRA_STORAGE_STATE)" --login-url="$(JIRA_LOGIN_URL)" --force-login="$(JIRA_FORCE_LOGIN)"
jira-check: ; npx -y --package github:formonkey/jira-issue-context-mcp#main jira-issue-check --base-url="$(JIRA_BASE_URL)" --cookie-name="$(JIRA_COOKIE_NAME)"

If Playwright reports that its browser executable is missing, run the install target once:

make jira-install-browser

For Atlassian SSO, prefer a login URL whose query contains application=jira. Some Atlassian admin/user-access URLs use application values such as admin--...; those flows may hide the Microsoft SSO option even though the normal Jira application flow works.

After make jira-login, verify the session:

make jira-check

The check should call Jira /rest/api/3/myself with:

Cookie: tenant.session.token=<JIRA_SESSION_TOKEN>

and return HTTP 200 OK. Once this works, restart the MCP client so it reads the updated .env.

MCP Client Configuration

This server uses the MCP stdio transport. Every MCP client needs to start a local command and pass the Jira environment file:

node /absolute/path/to/jira-issue-context-mcp/dist/index.js --env-file=/absolute/path/to/your/project/.env

Recommended setup:

1. Clone or vendor this repository.

2. Run npm install and npm run build.

3. Create a project .env with JIRA_BASE_URL and one auth method.

4. Configure your MCP client to run node dist/index.js --env-file=....

5. Restart or reload the client and check that the tools are visible.

Keep secrets in .env, shell env, keychains, or client secret stores. Do not commit Jira tokens.

Tool Selection Guidance

Tell the agent this mapping so it uses the right tool:

• Use jira_issue_help when unsure which Jira MCP tool fits the request.

• Use jira_issue_search when the user gives a JQL or asks for pending Jira tasks.

• Use jira_issue_workflow before opening implementation work for an issue.

• Use jira_issue_context when the agent needs the full description, comments, attachments, and images for one issue.

Good router prompt:

Actua como router. Ejecuta este JQL y trabaja en las tareas en paralelo:

project = XXXX AND statusCategory != Done ORDER BY priority DESC, updated ASC

Usa jira_issue_search con maxIssues=5 para obtener las claves.
Para cada clave, usa jira_issue_workflow.
Si routerAction es ready_for_agent_work, delega a jira-pm para obtener contexto con jira_issue_context.
Crea una conversacion o rama por tarea siguiendo el patron feature/XXXX-123.
No hagas escrituras en Jira desde este MCP; es read-only.

Codex

Project-level config goes in .codex/config.toml.

Local checkout:

[mcp_servers.jira_issue]
command = "node"
args = [
  "/absolute/path/to/jira-issue-context-mcp/dist/index.js",
  "--env-file=/absolute/path/to/your/project/.env"
]
cwd = "/absolute/path/to/your/project"
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 90
default_tools_approval_mode = "auto"

Directly from GitHub with npx:

[mcp_servers.jira_issue]
command = "npx"
args = [
  "-y",
  "--package",
  "github:formonkey/jira-issue-context-mcp#main",
  "jira-issue-mcp",
  "--env-file=/absolute/path/to/your/project/.env"
]
cwd = "/absolute/path/to/your/project"
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 90
default_tools_approval_mode = "auto"

Codex project instructions can include:

When Jira context is needed, use the jira_issue MCP server.
For JQL task discovery use jira_issue_search.
For router triage use jira_issue_workflow.
For full issue context use jira_issue_context.

Claude Code

Claude Code can load MCP servers from a project .mcp.json, user scope, or local scope. For team-shared configuration, put this in .mcp.json at the project root:

{
  "mcpServers": {
    "jira-issue": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/absolute/path/to/jira-issue-context-mcp/dist/index.js",
        "--env-file=/absolute/path/to/your/project/.env"
      ],
      "env": {}
    }
  }
}

Equivalent CLI command:

claude mcp add --transport stdio --scope project jira-issue -- \
  node /absolute/path/to/jira-issue-context-mcp/dist/index.js \
  --env-file=/absolute/path/to/your/project/.env

Verify in Claude Code:

claude mcp list

Inside Claude Code, run:

/mcp

If you already configured the server in Claude Desktop, Claude Code can import compatible servers on supported platforms:

claude mcp add-from-claude-desktop

Claude Desktop

Claude Desktop local MCP configuration is separate from Claude Code. Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "jira-issue": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/absolute/path/to/jira-issue-context-mcp/dist/index.js",
        "--env-file=/absolute/path/to/your/project/.env"
      ],
      "env": {}
    }
  }
}

Restart Claude Desktop after editing the file. If tools do not appear, confirm that npm run build has produced dist/index.js and that the .env path is absolute.

GitHub Copilot in VS Code

VS Code MCP configuration uses a top-level servers object. For a workspace-shared setup, create .vscode/mcp.json:

{
  "servers": {
    "jira-issue": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/absolute/path/to/jira-issue-context-mcp/dist/index.js",
        "--env-file=/absolute/path/to/your/project/.env"
      ]
    }
  }
}

Then:

1. Reload VS Code.

2. Open Copilot Chat.

3. Use Agent mode.

4. Open the tools picker and confirm jira-issue tools are listed.

For personal VS Code configuration, use the command palette action MCP: Open User Configuration and add the same server under servers.

GitHub Copilot CLI

Copilot CLI uses mcpServers. Add a user-level server:

copilot mcp add jira-issue --type stdio -- \
  node /absolute/path/to/jira-issue-context-mcp/dist/index.js \
  --env-file=/absolute/path/to/your/project/.env

Verify:

copilot mcp list
copilot mcp get jira-issue

Workspace-level Copilot CLI configs can be stored in .mcp.json or .github/mcp.json:

{
  "mcpServers": {
    "jira-issue": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/absolute/path/to/jira-issue-context-mcp/dist/index.js",
        "--env-file=/absolute/path/to/your/project/.env"
      ]
    }
  }
}

Copilot CLI requires tool-call permission even for read-only MCP tools.

GitHub Copilot Custom Agent

For a Copilot custom agent profile, configure this MCP under mcp-servers and list the tools the agent may use:

---
name: jira-router
description: Routes Jira issues into implementation work.
tools:
  - jira-issue/jira_issue_search
  - jira-issue/jira_issue_workflow
  - jira-issue/jira_issue_context
mcp-servers:
  jira-issue:
    type: local
    command: node
    args:
      - /absolute/path/to/jira-issue-context-mcp/dist/index.js
      - --env-file=/absolute/path/to/your/project/.env
    tools: ["*"]
---

Actua como router de Jira. Usa jira_issue_search para JQL, jira_issue_workflow
para triage y jira_issue_context para contexto completo.

For cloud agents, configure Jira secrets as repository or organization agent secrets/variables instead of hardcoding them.

Gemini CLI

Gemini CLI uses mcpServers in settings.json. Project-level config goes in .gemini/settings.json; user-level config goes in ~/.gemini/settings.json.

{
  "mcpServers": {
    "jira-issue": {
      "command": "node",
      "args": [
        "/absolute/path/to/jira-issue-context-mcp/dist/index.js",
        "--env-file=/absolute/path/to/your/project/.env"
      ],
      "timeout": 30000,
      "trust": false
    }
  }
}

Gemini CLI also supports adding the server from the command line:

gemini mcp add jira-issue node /absolute/path/to/jira-issue-context-mcp/dist/index.js -- \
  --env-file=/absolute/path/to/your/project/.env

Verify:

gemini mcp list

Inside Gemini CLI:

/mcp

Avoid underscores in Gemini MCP server aliases; use jira-issue instead of jira_issue.

Cursor

Cursor uses mcpServers. Project-level config goes in .cursor/mcp.json; global config goes in ~/.cursor/mcp.json.

{
  "mcpServers": {
    "jira-issue": {
      "command": "node",
      "args": [
        "/absolute/path/to/jira-issue-context-mcp/dist/index.js",
        "--env-file=/absolute/path/to/your/project/.env"
      ],
      "env": {}
    }
  }
}

Use Cursor Agent/Composer and ask for the tool by purpose:

Use the Jira MCP to fetch workflow triage for XXXX-123 before implementing.

Continue

Continue can load MCP server blocks from .continue/mcpServers/. Create .continue/mcpServers/jira-issue.yaml:

name: Jira Issue MCP
version: 1.0.0
schema: v1
mcpServers:
  - name: Jira Issue
    type: stdio
    command: node
    args:
      - /absolute/path/to/jira-issue-context-mcp/dist/index.js
      - --env-file=/absolute/path/to/your/project/.env

Continue also supports copying JSON-style MCP config files into .continue/mcpServers/, so the generic mcpServers JSON block below also works there.

Windsurf / Cascade

Windsurf uses a global mcp_config.json. Open Cascade's MCP settings, choose the raw config, and add:

{
  "mcpServers": {
    "jira-issue": {
      "command": "node",
      "args": [
        "/absolute/path/to/jira-issue-context-mcp/dist/index.js",
        "--env-file=/absolute/path/to/your/project/.env"
      ]
    }
  }
}

After saving, refresh MCP servers from the Windsurf/Cascade MCP toolbar. If your Windsurf version does not interpolate env vars, keep using --env-file as shown.

Generic MCP Clients

Most MCP clients accept a config shaped like this:

{
  "mcpServers": {
    "jira-issue": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/absolute/path/to/jira-issue-context-mcp/dist/index.js",
        "--env-file=/absolute/path/to/your/project/.env"
      ],
      "env": {}
    }
  }
}

Some clients use servers instead of mcpServers and some call stdio local. Keep the command and args the same.

Troubleshooting MCP Clients

• Run npm run build before configuring clients; they execute dist/index.js.

• Use an absolute --env-file path.

• Restart or reload the client after changing MCP config or .env.

• Check that JIRA_BASE_URL and exactly one auth method are valid.

• Run node dist/check-cli.js --env-file=/absolute/path/to/your/project/.env if auth fails.

• If the client shows the server but no tools, inspect the client's MCP logs and confirm stdout is not used for logs. This server writes diagnostics to stderr.

• If a JQL returns too many issues, lower maxIssues or set JIRA_DEFAULT_JQL_MAX_ISSUES=5.

Reference Docs

• Codex uses project .codex/config.toml for MCP server configuration.

• Claude Code MCP configuration: https://code.claude.com/docs/en/mcp

• Claude Desktop MCP support: https://support.anthropic.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop

• VS Code MCP configuration: https://code.visualstudio.com/docs/agents/reference/mcp-configuration

• GitHub Copilot CLI MCP configuration: https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference

• GitHub Copilot custom agents with MCP: https://docs.github.com/en/copilot/reference/custom-agents-configuration

• Gemini CLI MCP configuration: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md

• Cursor MCP configuration: https://docs.cursor.com/context/model-context-protocol

• Continue MCP configuration: https://docs.continue.dev/customize/deep-dives/mcp

• Windsurf MCP configuration example: https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/get-started/tools/windsurf