Jira CLI MCP Server

# Jira CLI MCP Server [](https://github.com/choplin/jira-cli-mcp/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) [](https://modelcontextprotocol.io) MCP (Model Context Protocol) server that wraps the `jira-cli` command-line tool to enable AI assistants to interact with Jira. ## Why jira-cli-mcp? If you're looking for a Jira MCP server, here's what makes jira-cli-mcp unique: - **🚀 Leverage Existing Tools** - Works seamlessly with your existing jira-cli setup and authentication - **🔒 Security-First** - No API tokens in config files; authentication handled by jira-cli - **🪶 Lightweight** - Just a Bun process, no Docker or containers required ### When to use mcp-atlassian instead? Choose [mcp-atlassian](https://github.com/sooperset/mcp-atlassian) if you: - Need **Confluence** support (we're Jira-only) - Prefer **Docker** deployment - Want a **self-contained** solution without CLI dependencies - Need **direct API** integration rather than CLI wrapping ## Features - **create_ticket** - Create new Jira tickets with customizable fields - **list_tickets** - Search and list Jira tickets using JQL queries - **get_ticket** - Get detailed ticket information including comments - **update_ticket_description** - Update ticket descriptions with rich text formatting - **add_comment** - Add comments to tickets with Markdown support - **assign_to_me** - Assign tickets to the current user - **move_ticket** - Move tickets between different statuses - **open_ticket_in_browser** - Open a Jira ticket in the default web browser ## Quick Start 1. Install and configure [jira-cli](https://github.com/ankitpokhrel/jira-cli) ([Installation guide](https://github.com/ankitpokhrel/jira-cli/wiki/Installation)): ```bash # Install jira-cli (macOS) brew install ankitpokhrel/jira-cli/jira-cli # Configure jira-cli with your Jira instance jira init ``` 2. Install jira-cli-mcp: ```bash brew tap choplin/jira-cli-mcp brew install jira-cli-mcp ``` 3. Add to Claude Desktop config (see [Setup](#setup-for-claude-desktop) below) ## Prerequisites - [jira-cli](https://github.com/ankitpokhrel/jira-cli) installed and authenticated - [Bun](https://bun.sh) runtime (only needed for development or if installing from source) ## Installation ### Option 1: Install via Homebrew (macOS/Linux) ```bash brew tap choplin/jira-cli-mcp brew install jira-cli-mcp ``` ### Option 2: Install via npm ```bash # Install globally with npm npm install -g @choplin/jira-cli-mcp # Or with Bun bun install -g @choplin/jira-cli-mcp ``` ### Option 3: Download Binary Download the pre-compiled binary for your platform from the [releases page](https://github.com/choplin/jira-cli-mcp/releases): - macOS (Apple Silicon): `jira-cli-mcp-darwin-arm64.tar.gz` - macOS (Intel): `jira-cli-mcp-darwin-x64.tar.gz` - Linux (x64): `jira-cli-mcp-linux-x64.tar.gz` - Linux (ARM64): `jira-cli-mcp-linux-arm64.tar.gz` ```bash # Example for macOS (Apple Silicon) tar -xzf jira-cli-mcp-darwin-arm64.tar.gz chmod +x jira-cli-mcp-darwin-arm64 sudo mv jira-cli-mcp-darwin-arm64 /usr/local/bin/jira-cli-mcp ``` ### Option 4: Build from Source ```bash git clone https://github.com/choplin/jira-cli-mcp.git cd jira-cli-mcp bun install bun run build:prod ``` ## Setup for Claude Desktop ### Option 1: Using Homebrew Installation (Recommended) If you installed via Homebrew (as shown in Quick Start), add to your `claude_desktop_config.json`: ```json { "mcpServers": { "jira-cli": { "command": "jira-cli-mcp" } } } ``` ### Option 2: Using npm Package Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "jira-cli": { "command": "npx", "args": ["@choplin/jira-cli-mcp"] } } } ``` Or if installed globally: ```json { "mcpServers": { "jira-cli": { "command": "jira-cli-mcp" } } } ``` ### Option 3: Using Pre-compiled Binary (No Dependencies) 1. Download the binary for your platform from [releases](https://github.com/choplin/jira-cli-mcp/releases) 2. Extract and move to your PATH: ```bash tar -xzf jira-cli-mcp-darwin-arm64.tar.gz sudo mv jira-cli-mcp-darwin-arm64 /usr/local/bin/jira-cli-mcp ``` 1. Add to config: ```json { "mcpServers": { "jira-cli": { "command": "jira-cli-mcp" } } } ``` ### Option 4: Build from Source 1. Clone and run directly: ```bash git clone https://github.com/choplin/jira-cli-mcp.git cd jira-cli-mcp bun install ``` 1. Add to config: ```json { "mcpServers": { "jira-cli": { "command": "bun", "args": ["run", "/path/to/jira-cli-mcp/src/index.ts"] } } } ``` ### Configuration Location The config file is typically located at: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Linux: `~/.config/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` ### Verification After setup, restart Claude Desktop and check if the MCP server is loaded by asking Claude about available Jira tools. ## Setup for Other AI Assistants ### Claude Code Claude Code has built-in support for MCP servers. To use jira-cli-mcp in your project: 1. First install jira-cli-mcp using one of the methods in the [Installation](#installation) section 2. Create a `.claude/mcp.json` file in your project root: ```json { "servers": { "jira-cli": { "command": "jira-cli-mcp" } } } ``` 1. Restart Claude Code and the MCP server will be automatically loaded You can then use Jira commands directly in your conversation, such as: - "List my open Jira tickets" - "Show me details for PROJ-123" - "Add a comment to PROJ-456" ### GitHub Copilot (VS Code) GitHub Copilot supports MCP servers in Visual Studio Code (version 1.99+): 1. First install jira-cli-mcp using one of the methods in the [Installation](#installation) section 2. Create `.vscode/mcp.json` in your repository: ```json { "servers": { "jira-cli": { "command": "jira-cli-mcp" } } } ``` 1. Open the `.vscode/mcp.json` file in VS Code and click the **[Start]** button to activate the server 2. In Copilot Chat: - Open Copilot Chat panel - Select "Agent" from the popup menu - Click the tools icon to see available MCP servers **Note**: MCP support in GitHub Copilot is currently in public preview. ## Development ### Running Tests ```bash # Run unit tests only bun test # Run all tests including integration tests bun run test:integration # Run integration tests with a specific test ticket JIRA_CLI_MCP_TEST_TICKET=PROJ-123 bun run test:integration ``` ### Environment Variables - `JIRA_CLI_PATH` - Custom path to jira-cli executable (default: "jira") #### Development Environment Variables - `JIRA_CLI_MCP_TEST_TICKET` - Ticket key for integration tests (required for non-listing integration tests) - `INTEGRATION_TEST=true` - Enable integration tests ### Type Checking ```bash bun run typecheck ``` ### Linting and Formatting ```bash bun run lint bun run format ``` ## Architecture - `src/tools/` - MCP tool implementations - `src/utils/` - Shared utilities and types - `tests/` - Unit tests with mocked jira-cli - `tests/integration/` - Integration tests with real jira-cli ## Notes - The server uses Atlassian Document Format (ADF) for rich text handling - Markdown input is automatically converted to ADF by jira-cli - All integration tests require proper jira-cli authentication ## Troubleshooting ### Common Issues 1. **"jira-cli not found" error** - Ensure jira-cli is installed: `which jira` - If using a custom path, set `JIRA_CLI_PATH` environment variable 2. **Authentication errors** - Run `jira me` to verify authentication - Re-authenticate with `jira init` if needed 3. **MCP server not showing in Claude Desktop** - Verify the config file path is correct - Ensure the path in config uses absolute paths, not relative - Restart Claude Desktop after config changes 4. **Permission errors on macOS** - Grant terminal/Claude Desktop full disk access in System Preferences - Ensure jira-cli has necessary permissions ### Debug Mode To see detailed logs, you can run the server manually: ```bash cd /path/to/jira-cli-mcp bun run src/index.ts ``` ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.