mcp-jira

This MCP server provides a Jira integration for Claude Code, exposing a suite of Jira capabilities via the MCP protocol. It includes comprehensive issue management (creating, updating, retrieving, searching, transitioning, linking, and diagnosing fields), comments and history, attachments, and sprint/board operations. With these tools you can create and update issues with advanced field support, read detailed issue and comment histories, attach files, manage sprint contents and boards, and perform batch operations across multiple issues. The server is designed to auto-handle Jira field mappings and supports localization, privacy-friendly handling of credentials, and flexible configuration through environment variables or a Claude Code settings file.

To use it, configure the MCP server in Claude Code or your environment so Claude Code can invoke the MCP server. Typical commands point Node to the built server file (dist/index.js) after a build. You’ll provide Jira credentials and project context via environment variables or a .env file. Once started, you can issue natural-language prompts that map to Jira actions, such as creating issues, updating fields, or generating standup or sprint planning prompts using the included prompts and tooling.

Key capabilities include creating issues with full field support (including custom fields and dates), searching with JQL or filters, managing epics and subtasks, reading and adding comments, uploading attachments, and sprint operations like creating sprints or moving issues between sprints. The server also exposes utilities for diagnosing field configurations, listing available fields, and providing helpful prompts for project planning and release notes.

Prerequisites:

• Node.js 18.x or higher
• npm (comes with Node.js)
• A Jira account with API token access

Installation steps:

1. Clone the repository:

git clone https://github.com/tom28881/JIRA_MCP.git
cd JIRA_MCP

2. Install dependencies:

npm install

3. Build the project (produces dist/index.js):

npm run build

4. Create a .env file from the example (or set environment variables directly):

cp .env.example .env

5. Populate Jira credentials in the environment/config:

# Example values to set in .env or export in your session
export JIRA_HOST="https://your-company.atlassian.net"
export JIRA_EMAIL="your-email@company.com"
export JIRA_API_TOKEN="your-api-token"
export JIRA_DEFAULT_PROJECT="PROJ"

6. Run Claude Code with the MCP server configured (example):

claude --mcp "node dist/index.js"

7. Alternatively, configure Claude Code to point at the exact path of the compiled MCP entry:

• Command: node
• Args: ["/absolute/path/to/mcp-jira-server/dist/index.js"]
• Env: include JIRA_HOST, JIRA_EMAIL, JIRA_API_TOKEN, JIRA_DEFAULT_PROJECT

Tips and considerations:

• Never commit credentials; use environment variables or a .env file as recommended.
• If you change Jira field IDs, you can rely on auto-detection by default; you can also explicitly set field IDs in your environment if needed.
• For local testing, you can use the provided prompts to generate standup reports, sprint plans, or release notes as part of Claude Code workflows.
• If you encounter token-related errors, verify that JIRA_API_TOKEN has the correct permissions and that JIRA_HOST, JIRA_EMAIL, and default project are correctly configured.
• The MCP server supports localization and will handle multiple Jira locales; ensure your Jira instance supports the fields you intend to use.
• Review the Dist build artifacts after npm run build to confirm dist/index.js exists before starting Claude Code.
• For troubleshooting, use the diagnose-fields tool to verify custom field IDs when needed.