Jira Stories MCP Server

# Jira MCP Server A Model Context Protocol (MCP) server that provides comprehensive integration with Jira. This server enables AI assistants to interact with Jira through a standardized interface, allowing them to search, create, update, and manage Jira issues programmatically. ## Features This MCP server provides the following tools for Jira integration: - **🔍 Search Issues** - Search for issues using JQL (Jira Query Language) - **📄 Get Issue Details** - Retrieve detailed information about specific issues - **➕ Create Issues** - Create new issues in any project - **✏️ Update Issues** - Modify existing issue fields - **💬 Add Comments** - Add comments to issues - **🔄 Get Transitions** - View available status transitions - **⚡ Transition Issues** - Change issue status/workflow state - **👤 Assign Issues** - Assign issues to users - **📋 List Projects** - Get all accessible projects - **🔎 Search Users** - Find users by name or email - **📝 Get Comments** - Retrieve all comments from an issue - **📊 Get Boards** - List all accessible Scrum and Kanban boards - **📈 Get Board Issues** - Retrieve issues from a specific board ## Prerequisites Before you begin, ensure you have: - Node.js 18 or higher installed - A Jira account (Cloud or Data Center) - Jira API credentials (email and API token) - Claude Desktop or another MCP-compatible client ## Installation ### 1. Clone or Download ```bash git clone <repository-url> cd jira-mcp ``` Or if you're starting from scratch in this directory, the files are already created. ### 2. Install Dependencies ```bash npm install ``` This will install: - `@modelcontextprotocol/sdk` - MCP SDK for building servers - `axios` - HTTP client for Jira API calls - `dotenv` - Environment variable management - TypeScript and Node.js type definitions ### 3. Build the Project ```bash npm run build ``` This compiles the TypeScript code to JavaScript in the `build/` directory. ## Configuration ### Step 1: Get Your Jira API Token 1. Log in to your Jira account at `https://your-domain.atlassian.net` 2. Go to **Account Settings** → **Security** → **API tokens** 3. Click **Create API token** 4. Give it a label (e.g., "MCP Server") and click **Create** 5. **Copy the token immediately** (you won't be able to see it again) ### Step 2: Create Environment File Create a `.env` file in the root directory: ```bash JIRA_HOST=your-domain.atlassian.net JIRA_EMAIL=your-email@example.com JIRA_API_TOKEN=your-api-token-here ``` **Important Notes:** - `JIRA_HOST` should be just the domain without `https://` - Use the email associated with your Jira account - Keep your API token secure and never commit it to version control ### Step 3: Configure Claude Desktop Add the server to your Claude Desktop configuration file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "jira": { "command": "node", "args": ["/ABSOLUTE/PATH/TO/jira-mcp/build/index.js"], "env": { "JIRA_HOST": "your-domain.atlassian.net", "JIRA_EMAIL": "your-email@example.com", "JIRA_API_TOKEN": "your-api-token-here" } } } } ``` **Replace** `/ABSOLUTE/PATH/TO/jira-mcp` with the actual absolute path to your project directory. ### Step 4: Restart Claude Desktop Completely quit and restart Claude Desktop for the changes to take effect. ## Usage Once configured, you can ask Claude to interact with Jira using natural language. Here are some examples: ### Example Queries #### Search for Issues ``` "Find all open bugs in the PROJ project" "Show me issues assigned to me that are in progress" "Search for issues created this week with high priority" ``` Behind the scenes, Claude will use JQL like: - `project = PROJ AND type = Bug AND status = Open` - `assignee = currentUser() AND status = "In Progress"` - `created >= -1w AND priority = High` #### Get Issue Details ``` "Show me the details of issue PROJ-123" "What's the status of PROJ-456?" ``` #### Create New Issues ``` "Create a new bug in project PROJ with summary 'Login page not loading' and description 'Users cannot access the login page'" "Create a task in PROJ called 'Update documentation' with high priority" ``` #### Update Issues ``` "Update PROJ-123 to change the summary to 'Fix login page loading issue'" "Change the priority of PROJ-456 to High" ``` #### Add Comments ``` "Add a comment to PROJ-123 saying 'This has been fixed in the latest release'" "Comment on PROJ-456: 'Waiting for QA team to verify'" ``` #### Transition Issues ``` "Move PROJ-123 to In Progress" "Close PROJ-456" ``` For transitions, Claude will first get available transitions using `jira_get_transitions`, then execute the appropriate one. #### Assign Issues ``` "Assign PROJ-123 to john.doe@example.com" "Unassign PROJ-456" ``` You'll need the user's account ID, which Claude can find using `jira_search_users`. #### List Projects ``` "What Jira projects do I have access to?" "Show me all available projects" ``` #### Search Users ``` "Find user john.doe" "Search for users named Smith" ``` #### Get Boards ``` "Show me all available boards" "List all Scrum boards" "What boards do I have access to?" ``` #### Get Board Issues ``` "Show me all issues from board 123" "Get all stories from the development board" "List issues from board 456 that are in progress" ``` ## Available Tools Reference ### jira_search_issues Search for issues using JQL. **Parameters:** - `jql` (required): JQL query string - `maxResults` (optional): Maximum results (default: 50) - `startAt` (optional): Starting index (default: 0) **Example:** ```json { "jql": "project = PROJ AND status = Open", "maxResults": 10 } ``` ### jira_get_issue Get detailed information about an issue. **Parameters:** - `issueKey` (required): Issue key (e.g., "PROJ-123") **Example:** ```json { "issueKey": "PROJ-123" } ``` ### jira_create_issue Create a new issue. **Parameters:** - `projectKey` (required): Project key - `summary` (required): Issue summary - `issueType` (required): Issue type (Bug, Task, Story, etc.) - `description` (optional): Issue description - `priority` (optional): Priority (High, Medium, Low, etc.) **Example:** ```json { "projectKey": "PROJ", "summary": "Fix login bug", "issueType": "Bug", "description": "Login page not loading", "priority": "High" } ``` ### jira_update_issue Update an existing issue. **Parameters:** - `issueKey` (required): Issue key - `summary` (optional): Updated summary - `description` (optional): Updated description - `priority` (optional): Updated priority **Example:** ```json { "issueKey": "PROJ-123", "summary": "Updated summary", "priority": "High" } ``` ### jira_add_comment Add a comment to an issue. **Parameters:** - `issueKey` (required): Issue key - `comment` (required): Comment text **Example:** ```json { "issueKey": "PROJ-123", "comment": "This has been fixed" } ``` ### jira_get_transitions Get available transitions for an issue. **Parameters:** - `issueKey` (required): Issue key **Example:** ```json { "issueKey": "PROJ-123" } ``` ### jira_transition_issue Transition an issue to a new status. **Parameters:** - `issueKey` (required): Issue key - `transitionId` (required): Transition ID (from get_transitions) **Example:** ```json { "issueKey": "PROJ-123", "transitionId": "31" } ``` ### jira_assign_issue Assign an issue to a user. **Parameters:** - `issueKey` (required): Issue key - `accountId` (required): User account ID (use null to unassign) **Example:** ```json { "issueKey": "PROJ-123", "accountId": "5d123456789abc0def123456" } ``` ### jira_get_projects Get all accessible projects. No parameters required. ### jira_search_users Search for users. **Parameters:** - `query` (required): Search query (name or email) **Example:** ```json { "query": "john.doe" } ``` ### jira_get_comments Get all comments from an issue. **Parameters:** - `issueKey` (required): Issue key **Example:** ```json { "issueKey": "PROJ-123" } ``` ### jira_get_boards Get a list of all accessible Jira boards (Scrum and Kanban). **Parameters:** - `startAt` (optional): Starting index (default: 0) - `maxResults` (optional): Maximum results (default: 50) **Example:** ```json { "startAt": 0, "maxResults": 50 } ``` ### jira_get_board_issues Get issues from a specific Jira board. Useful for retrieving stories, tasks, and bugs from a board. **Parameters:** - `boardId` (required): Board ID number - `startAt` (optional): Starting index (default: 0) - `maxResults` (optional): Maximum results (default: 50) - `jql` (optional): JQL filter to apply to board issues **Example:** ```json { "boardId": 123, "jql": "type = Story AND status = 'In Progress'", "maxResults": 20 } ``` ## Development ### Project Structure ``` jira-mcp/ ├── src/ │ ├── index.ts # Main MCP server implementation │ └── jira-client.ts # Jira API client wrapper ├── build/ # Compiled JavaScript (generated) ├── package.json # Project dependencies ├── tsconfig.json # TypeScript configuration ├── .env # Environment variables (create this) ├── .gitignore # Git ignore rules └── README.md # This file ``` ### Available Scripts - `npm run build` - Compile TypeScript to JavaScript - `npm run watch` - Watch mode for development - `npm run dev` - Run with Node.js debugger ### Making Changes 1. Edit TypeScript files in `src/` 2. Run `npm run build` to compile 3. Restart Claude Desktop to test changes ## Troubleshooting ### Server Not Appearing in Claude 1. Check that the path in `claude_desktop_config.json` is absolute and correct 2. Verify the `build/index.js` file exists (run `npm run build`) 3. Completely quit and restart Claude Desktop (not just close the window) 4. Check Claude Desktop logs for errors ### Authentication Errors - Verify your `JIRA_HOST` doesn't include `https://` - Confirm your API token is valid and hasn't expired - Ensure the email matches your Jira account - Check that your account has permission to access the Jira instance ### API Errors - Check that project keys and issue keys are correct (case-sensitive) - Verify you have permission to perform the operation - Some operations may require specific Jira permissions - Review the error message returned by the tool ### JQL Query Issues - Test your JQL in Jira's search interface first - Ensure field names are correct and quoted if they contain spaces - Use proper JQL operators (=, !=, IN, NOT IN, etc.) - Common fields: `project`, `status`, `assignee`, `priority`, `type`, `created`, `updated` ## Security Notes - Never commit your `.env` file or API tokens - API tokens have the same permissions as your user account - Consider creating a dedicated service account for automation - Regularly rotate your API tokens - Use environment variables for all sensitive data ## JQL Reference Common JQL examples: ```jql # Issues in a project project = PROJ # Open bugs project = PROJ AND type = Bug AND status = Open # Assigned to me assignee = currentUser() # High priority issues priority = High # Created recently created >= -7d # Multiple conditions project = PROJ AND status IN (Open, "In Progress") AND assignee = currentUser() ``` ## API Rate Limits Jira Cloud has rate limits: - 10 requests per second per user - Consider implementing delays for bulk operations - The server handles individual requests; batch operations may hit limits ## License MIT ## Support For issues and questions: - Check the troubleshooting section above - Review Jira API documentation: https://developer.atlassian.com/cloud/jira/platform/rest/v3/ - Review MCP documentation: https://modelcontextprotocol.io ## Contributing Contributions are welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Submit a pull request --- **Note**: This is an unofficial tool and is not affiliated with or endorsed by Atlassian.