# 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)

```bash
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)

```bash
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

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

Then add with local binary:

```bash
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
```

```bash
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:

```json
{
  "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](https://id.atlassian.com/manage-profile/security/api-tokens).
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:

```bash
npm install
```

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

3. Build:

```bash
npm run build
```

4. Start:

```bash
npm start
```

Development mode:

```bash
npm run dev
```

## MCP Configuration Examples

Use this server entry in your MCP client config:

```json
{
  "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

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

## Example Output

```json
{
  "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`.