A comprehensive Model Context Protocol (MCP) server for Jira integration with Claude Code. This server provides complete Jira functionality including issue management, sprint operations, comments, attachments, and batch processing. ⚠️ Security Note: Never commit your API tokens! All credentials should be in .env files or environment variables. - create-issue - Create issues with full field support
Add this skill
npx mdskills install tom28881/mcp-jira-serverComprehensive Jira MCP server with extensive tools, localization support, and strong documentation
1# MCP Jira Server fo Claude Code23A comprehensive Model Context Protocol (MCP) server for Jira integration with Claude Code. This server provides complete Jira functionality including issue management, sprint operations, comments, attachments, and batch processing.45[](https://opensource.org/licenses/MIT)6[](https://www.typescriptlang.org/)7[](https://nodejs.org/)89⚠️ **Security Note**: Never commit your API tokens! All credentials should be in `.env` files or environment variables.1011## 🚀 Features1213### 📋 Issue Management (12 tools)14- **create-issue** - Create issues with full field support including custom fields and dates15- **update-issue** - Update existing issues with smart field handling16- **get-issue** - Retrieve detailed issue information17- **search-issues** - Advanced search using JQL or simplified filters with date support18- **transition-issue** - Move issues through workflow states19- **link-issues** - Create relationships between issues (with smart type matching)20- **get-link-types** - List available issue link types21- **get-fields** - Show available fields for project/issue type22- **diagnose-fields** - Troubleshoot field configuration and find custom field IDs23- **create-epic-with-subtasks** - Create epic with multiple subtasks in one operation24- **create-task-for-epic** - Create task linked to epic (optimized for localized Jira)2526### 💬 Comments & History (3 tools)27- **get-comments** - Read issue comments with author and timestamp information28- **get-history** - View detailed change history with field modifications29- **add-comment** - Add comments with Atlassian Document Format support30- **batch-comment** - Add same comment to multiple issues simultaneously3132### 📎 Attachments (2 tools)33- **get-attachments** - List attachments with metadata (size, type, upload date)34- **upload-attachment** - Upload files using base64 encoding3536### 🏃 Sprint & Agile Management (4 tools)37- **get-boards** - List available Jira boards for agile projects38- **get-sprints** - View sprints for a board with status indicators39- **move-issue-to-sprint** - Move issues between sprints and backlog40- **create-sprint** - Create new sprints with optional start/end dates4142### Resources43- `jira://projects` - List all accessible projects44- `jira://project/{key}` - Get specific project details45- `jira://issue/{key}` - Get specific issue details46- `jira://myself` - Current user information47- `jira://search?jql={query}` - Search results4849### Prompts50- **standup-report** - Generate daily standup reports51- **sprint-planning** - Assist with sprint planning activities52- **bug-triage** - Help prioritize and triage bugs53- **release-notes** - Generate release notes from completed issues54- **epic-status** - Comprehensive epic progress reports5556## Installation57581. Clone the repository:59```bash60git clone https://github.com/tom28881/JIRA_MCP.git61cd JIRA_MCP62```63642. Install dependencies:65```bash66npm install67```68693. Build the project:70```bash71npm run build72```73744. Create a `.env` file from the example:75```bash76cp .env.example .env77```78795. Configure your Jira credentials in `.env`:80```env81JIRA_HOST=https://your-company.atlassian.net82JIRA_EMAIL=your-email@company.com83JIRA_API_TOKEN=your-api-token84JIRA_DEFAULT_PROJECT=PROJ85```8687### Getting a Jira API Token88891. Log in to [Atlassian account settings](https://id.atlassian.com/manage-profile/security/api-tokens)902. Click "Create API token"913. Give it a name (e.g., "MCP Server")924. Copy the token and add it to your `.env` file9394## Claude Code Configuration9596To use this MCP server with Claude Code, you need to configure it in your MCP settings.9798### Option 1: Using Environment Variables99100Set up the server with environment variables:101102```bash103# Export environment variables104export JIRA_HOST="https://your-company.atlassian.net"105export JIRA_EMAIL="your-email@company.com"106export JIRA_API_TOKEN="your-api-token"107export JIRA_DEFAULT_PROJECT="PROJ"108109# Run Claude Code with the MCP server110claude --mcp "node /absolute/path/to/mcp-jira-server/dist/index.js"111```112113### Option 2: Using .env File114115Create a `.env` file in the server directory and run:116117```bash118cd /path/to/mcp-jira-server119claude --mcp "node dist/index.js"120# or use the convenient run script:121claude --mcp "./run.sh"122```123124### Option 3: Add to Claude Code Settings125126Add the server to your Claude Code settings file (`~/.claude/settings.json`):127128```json129{130 "mcpServers": [131 {132 "name": "jira",133 "command": "node",134 "args": ["/absolute/path/to/mcp-jira-server/dist/index.js"],135 "env": {136 "JIRA_HOST": "https://your-company.atlassian.net",137 "JIRA_EMAIL": "your-email@company.com",138 "JIRA_API_TOKEN": "your-api-token",139 "JIRA_DEFAULT_PROJECT": "PROJ"140 }141 }142 ]143}144```145146## Usage Examples147148### Creating Issues149150```151Create a new bug in project PROJ with high priority about login issues152```153154```155Create a story "Implement user authentication" with 5 story points and assign it to john@example.com156```157158### Setting Dates and Time Estimates159160```161Create task "Database backup" with dueDate "next week" and originalEstimate "4h"162```163164```165Update PROJ-123 with startDate "tomorrow" and dueDate "+14d"166```167168```169Create issue "Quarterly review" with dueDate "31.3.2025" and originalEstimate "2 days"170```171172### Creating Epics with Subtasks173174```175Create an epic "Database Migration" in project PROJ with subtasks "Backup current data" and "Migrate schema"176```177178### Creating Subtasks179180```181Create a subtask "Review code" for parent issue PROJ-123182```183184### Czech Jira Support185186```187Create issue type "Úkol" in project PROJ188```189190```191Create task for epic PPC-48 with summary "Database backup"192```193194### Searching Issues195196```197Find all open bugs assigned to me198```199200```201Search for issues in project PROJ with label "urgent" that are not done202```203204### Date-based Searching205206```207Search issues due before "next week" in project PROJ208```209210```211Find issues created after "2024-12-01" and updated after "yesterday"212```213214```215Search for overdue issues: dueBefore "today" and status != "Done"216```217218### Managing Issues219220```221Update PROJ-123 to add story points 8222```223224```225Transition PROJ-456 to "In Progress"226```227228```229Link PROJ-123 to PROJ-456 as "blocks"230```231232**Note**: Epic-Story relationships use the epicLink field, not regular issue links:233```234Update PROJ-456 with epicLink "PROJ-100" # Links story to epic235```236237### Using Prompts238239```240Generate a standup report for john@example.com241```242243```244Help me plan the sprint for project PROJ245```246247```248Create release notes for version 2.0 in project PROJ249```250251## Advanced Configuration252253### Custom Fields254255The server can work with any Jira configuration:256257#### Option 1: Auto-Detection (Recommended)258Leave custom field IDs unset in `.env` and the server will automatically detect them based on field names.259260#### Option 2: Manual Configuration261If auto-detection doesn't work, configure custom field IDs in your `.env`:262263```env264JIRA_FIELD_STORY_POINTS=customfield_10001265JIRA_FIELD_ACCEPTANCE_CRITERIA=customfield_10002266JIRA_FIELD_EPIC_LINK=customfield_10003267```268269#### Finding Field IDs270Use the `diagnose-fields` tool to find the correct field IDs for your Jira instance:271```272diagnose-fields project:"PROJ" issueType:"Story"273```274275### Auto-create Test Tickets276277Enable automatic test ticket creation for stories:278279```env280AUTO_CREATE_TEST_TICKETS=true281```282283## Development284285### Running in Development Mode286287```bash288npm run dev289```290291### Type Checking292293```bash294npm run typecheck295```296297### Linting298299```bash300npm run lint301```302303## Features304305### 🌍 Localization Support306- Automatic support for localized Jira instances (Czech, English, etc.)307- Issue type names can be in any language (e.g., "Task", "Úkol", "Aufgabe")308- Priority names support localization (e.g., "High", "Vysoká", "Hoch")309- Special support for Czech Jira configurations310- Works with any Jira language setting311312### 📅 Date and Time Management313- Flexible date input formats:314 - ISO: "2024-12-31"315 - European: "31.12.2024" or "31/12/2024"316 - Relative: "today", "tomorrow", "next week", "+7d", "+2w", "+1m"317 - Czech: "dnes", "zítra", "příští týden"318- Time tracking support:319 - Estimates: "2h", "1d 4h", "3 days", "2 hodiny"320 - Automatic format conversion321- Date-based searching and filtering322323### 🔄 Automatic Retry324The server automatically retries failed requests with exponential backoff (up to 3 attempts).325326### 📦 Robust Error Handling327- Empty response handling for Jira transitions328- Detailed error messages with context329- Graceful degradation for missing features330331### 📝 Comprehensive Logging332Enable debug logging to see detailed information:333```bash334DEBUG=* claude --mcp "./run.sh"335# or specific to jira-mcp:336DEBUG=jira-mcp claude --mcp "./run.sh"337```338339### 🔒 Connection Testing340The server tests the connection on startup and provides clear error messages if authentication fails.341342### 📄 Atlassian Document Format343Automatically converts plain text and markdown to Jira's ADF format for rich text fields.344345## Troubleshooting346347### Working with Different Jira Configurations348349This MCP server is designed to work with **any Jira instance** regardless of:350- Language settings (English, Czech, German, etc.)351- Custom field configurations352- Project-specific settings353354**Best Practices:**3551. Use `get-fields` to see available issue types in your language3562. Use `diagnose-fields` to find custom field IDs3573. Create issues using the exact issue type names from your Jira358359### Common Issues3603611. **Authentication Failed**362 - Verify your API token is correct363 - Ensure your email matches your Atlassian account364 - Check that your Jira instance URL includes `https://`3653662. **Project Not Found**367 - Verify you have access to the project368 - Check the project key is correct (case-sensitive)3693703. **Custom Fields Not Working**371 - Use `diagnose-fields` tool to find the correct field IDs for your project372 - Use `get-fields` tool to see all available fields373 - Custom field IDs typically start with `customfield_`374 - Some fields may not be available for certain issue types (e.g., labels on Epics)375 - Epic Link field ID varies between Jira instances3763774. **Link Type Not Found**378 - Use `get-link-types` tool to see available link types379 - Link types are case-sensitive in Jira API380 - The server will try to match case-insensitively381 - Epic-Story relationships use epicLink field, not regular issue links3823835. **Epic-Story Linking Issues**384 - Run `diagnose-fields` for project and "Story" issue type385 - Update JIRA_FIELD_EPIC_LINK in .env with the correct field ID386 - Restart the MCP server after updating .env387388### Debug Mode389390Set the `DEBUG` environment variable for verbose logging:391392```bash393DEBUG=* claude --mcp "./run.sh"394# or395DEBUG=jira-mcp claude --mcp "./run.sh"396```397398### View Logs399400Logs are output to stderr and include:401- Connection status402- API requests and responses403- Error details with context404- Performance metrics405406## Contributing407408See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.409410## License411412MIT License - see LICENSE file for details413414## Support415416For issues and feature requests, please use the GitHub issue tracker.417
Full transparency — inspect the skill content before installing.