Jira mcp

MCP server for Jira Server/Data Center (REST API v2). Lets an AI assistant (Claude Code, Claude Desktop, ...) read and write your Jira directly.

Requirements

• A Jira Server/Data Center account (username + password).
• Node.js 18+.

Quick start

Use Claude Code CLI:

claude mcp add jira-mcp npx -y g-jira-mcp@latest \
  --env JIRA_HOST="https://jira.company.com" \
  --env JIRA_USERNAME="your_username" \
  --env JIRA_PASSWORD="your_password"

Or manually add to .claude/settings.json (or claude_desktop_config.json):

{
  "mcpServers": {
    "jira-mcp": {
      "command": "npx",
      "args": ["-y", "g-jira-mcp@latest"],
      "env": {
        "JIRA_HOST": "https://jira.company.com",
        "JIRA_USERNAME": "your_username",
        "JIRA_PASSWORD": "your_password"
      }
    }
  }
}

Restart Claude Code/Desktop after editing the config.

Environment variables

| Variable | Required | Description | | ----------------------- | -------- | ------------------------------------------------------------------------------------------ | | JIRA_HOST | yes | Base URL, e.g. https://jira.company.com | | JIRA_USERNAME | yes | Jira username | | JIRA_PASSWORD | yes | Jira password | | JIRA_START_DATE_FIELD | no | Custom field ID for "Start date" (default customfield_11300, matches pm.gem-corp.tech) |

To discover custom field IDs on your instance:

curl -u user:pass https://jira.company.com/rest/api/2/field | jq '.[] | select(.name | test("story|point|start"; "i")) | {id, name}'

Tools

| Tool | Description | Key parameters | | ------------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | get_ticket | Get full details of a Jira ticket by its key | ticket_id | | search_tickets | Search Jira tickets using JQL query language | jql, max_results (optional, default 50) | | create_ticket | Create a new Jira ticket (Story, Task, Bug, Sub-task) | project, summary, issue_type, optional: body, parent_key, due_date, start_date, original_estimate, labels | | update_ticket | Update fields of a Jira ticket (summary, description, type, parent, labels, dates, estimate, assignee, notes) | ticket_id, optional: summary, description, issue_type, parent_key, labels, due_date, start_date, original_estimate, implementation_notes, assignee | | transition_ticket | Change the status of a Jira ticket by status name | ticket_id, status | | add_comment | Add a comment to a Jira ticket | ticket_id, body | | log_work | Log work (time) on a Jira ticket | ticket_id, time_spent, optional: comment, started | | link_issues | Create a link between two Jira tickets (e.g. Blocks, Relates to, Clones, Duplicate) | inward_issue, outward_issue, optional: link_type (default "Blocks") | | generate_release_notes | Generate Markdown release notes for a fix version, grouped by issue type | fix_version, optional: project |

Notes

• Jira Server uses plain text for descriptions — no ADF format.
• duedate is a standard field (YYYY-MM-DD); "Start date" is a custom field, configurable via JIRA_START_DATE_FIELD.
• search_tickets uses JQL syntax, e.g. project = GEM AND status = 'In Progress'.
• transition_ticket matches the target status by name and resolves the transition ID automatically.
• update_ticket only changes the fields you pass; omit a field to keep its current value. Pass assignee="" to unassign. implementation_notes appends to the description.
• generate_release_notes groups tickets by type into Features / Improvements / Bug Fixes / Other.
• All logs go to stderr; stdout is reserved for the MCP protocol.

Example prompts

• "Search tickets in project GEM that are In Progress"
• "Create a Story in GEM titled 'Release notes v2.0' due 2026-08-01"
• "Update GEM-234, set the assignee to namcp and add label BugFix"
• "Add a comment to GEM-234: 'Review done'"
• "Generate release notes for fix version v2.4 in project GEM"

Troubleshooting

• 401/403: recheck JIRA_USERNAME/JIRA_PASSWORD and whether the account can access the project.
• Connection/timeout: verify JIRA_HOST format (starts with https://, no trailing /), and whether VPN/internal network is required.
• Start date not saving: confirm JIRA_START_DATE_FIELD matches your instance (see the discovery command above).
• No error logs: server logs go to stderr — check the MCP client (Claude Code/Desktop) output, not stdout.

Development

pnpm install
cp .env.example .env   # edit with your credentials
pnpm build             # bundle to dist/index.js via esbuild
pnpm lint              # biome check + tsc + prettier (markdown)
pnpm release           # release-it: bumps version, commits, tags, pushes (runs lint + build first, no pre-commit needed)
pnpm archive           # package release/jira-mcp-v<version>.zip

Support

Questions or issues? Email NamCP.

If this project helps you, consider buying me a coffee: