jira-context-mcp

jira-context-mcp is a production-focused MCP server that fetches structured Jira issue context from a Jira URL. It is designed for coding agents like Codex and Claude Code so they can quickly understand issue intent and implementation context.

What This Server Does

• Exposes one MCP tool: get_jira_issue_from_url
• Validates that the input URL belongs to your JIRA_BASE_URL
• Extracts a Jira issue key from multiple Jira URL shapes
• Calls Jira Cloud REST API:
  • GET /rest/api/3/issue/{issueIdOrKey}?expand=names,renderedFields
• Converts Jira rich text (Atlassian Document Format) into plain text
• Returns concise, agent-friendly structured issue context

Supported Jira Issue Types

This server is issue-type agnostic. It works for any Jira issue type, including:

• Bug
• Feature request
• Task
• Story
• Epic
• Requirement
• Improvement
• Support ticket
• Custom issue types

Required Environment Variables

• JIRA_EMAIL: Jira account email
• JIRA_API_TOKEN: Jira API token
• JIRA_BASE_URL: Jira Cloud tenant URL (example: https://your-domain.atlassian.net)

Quick Setup Commands

Codex (no global install)

codex mcp add jira \
  --env JIRA_EMAIL=you@example.com \
  --env JIRA_API_TOKEN=your-token \
  --env JIRA_BASE_URL=https://your-domain.atlassian.net \
  -- npx -y github:TastyHeadphones/jira-context-mcp

Claude Code (no global install)

claude mcp add jira \
  -e JIRA_EMAIL=you@example.com \
  -e JIRA_API_TOKEN=your-token \
  -e JIRA_BASE_URL=https://your-domain.atlassian.net \
  -- npx -y github:TastyHeadphones/jira-context-mcp

Optional: install globally first

npm install -g github:TastyHeadphones/jira-context-mcp

Then add with local binary:

codex mcp add jira \
  --env JIRA_EMAIL=you@example.com \
  --env JIRA_API_TOKEN=your-token \
  --env JIRA_BASE_URL=https://your-domain.atlassian.net \
  -- jira-context-mcp

claude mcp add jira \
  -e JIRA_EMAIL=you@example.com \
  -e JIRA_API_TOKEN=your-token \
  -e JIRA_BASE_URL=https://your-domain.atlassian.net \
  -- jira-context-mcp

Tool

get_jira_issue_from_url

Input:

{
  "url": "string"
}

Supported URL examples:

• ${JIRA_BASE_URL}/browse/ABC-123
• ${JIRA_BASE_URL}/jira/software/projects/ABC/boards/1/backlog?selectedIssue=ABC-123
• Any Jira URL under JIRA_BASE_URL containing an issue key like ABC-123

Returned structured data includes:

• issueKey, issueUrl, summary
• description (plain text where possible)
• issueType, status, statusCategory, priority
• assignee, reporter
• labels, components
• fixVersions, affectedVersions
• created, updated, dueDate
• parent, epic
• subtasks, linkedIssues
• attachments (metadata only)
• comments (most recent 10)
• acceptanceCriteria (best-effort extraction from description/custom fields)
• customFields (non-empty, normalized, human-readable)

Create a Jira API Token

1. Open Atlassian API token settings.
2. Click Create API token.
3. Name the token and copy it.
4. Use that value for JIRA_API_TOKEN.

Run Locally

1. Install dependencies:

npm install

2. Set environment variables (for example via .env in your shell/session).

3. Build:

npm run build

4. Start:

npm start

Development mode:

npm run dev

MCP Configuration Examples

Use this server entry in your MCP client config:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/jira-context-mcp/dist/index.js"],
      "env": {
        "JIRA_EMAIL": "you@example.com",
        "JIRA_API_TOKEN": "your-token",
        "JIRA_BASE_URL": "https://your-domain.atlassian.net"
      }
    }
  }
}

Claude Code MCP configuration example

Use the same JSON block above in your Claude Code MCP server configuration file.

Codex MCP configuration example

Use the same JSON block above in your Codex MCP server configuration file.

Example Tool Call

{
  "name": "get_jira_issue_from_url",
  "arguments": {
    "url": "https://your-domain.atlassian.net/browse/ABC-123"
  }
}

Example Output

{
  "issueKey": "ABC-123",
  "issueUrl": "https://your-domain.atlassian.net/browse/ABC-123",
  "summary": "Prevent duplicate webhook retries",
  "description": "As a platform engineer, I need retry deduplication ...",
  "acceptanceCriteria": "- Duplicate deliveries are ignored\n- Metrics include dropped duplicates",
  "issueType": "Story",
  "status": "In Progress",
  "statusCategory": "In Progress",
  "priority": "High",
  "assignee": {
    "accountId": "5b10ac8d82e05b22cc7d4ef5",
    "displayName": "Alex Example",
    "emailAddress": null,
    "active": true
  },
  "labels": ["webhook", "idempotency"],
  "components": ["API"],
  "fixVersions": ["2026.05"],
  "affectedVersions": ["2026.04"],
  "subtasks": [],
  "linkedIssues": [],
  "attachments": [],
  "comments": [],
  "customFields": []
}

Security Notes

• Keep JIRA_API_TOKEN secret. Never commit it to source control.
• Use least-privilege Jira access for the account tied to the token.
• This server only fetches issue data and attachment metadata; it does not download attachment files.
• URL validation rejects URLs outside your configured JIRA_BASE_URL.