MCP Jira Server

A Model Context Protocol (MCP) server that integrates Jira with Claude Desktop, allowing you to fetch and view Jira issue details directly through Claude.

Features

• 🔍 Get Jira Issue Details: Fetch comprehensive information about any Jira issue by its key

• 📁 Browse Projects: List projects and view project details

• 🧭 Understand Workflows: See issue types and statuses per project

• 🔎 Search Issues (JQL): Flexible search with pagination and selected fields

• 📌 Project Issue Lists: Quickly list issues in a project

• 💬 Issue Comments: Read comments on an issue

• 🗂️ Agile Views: Boards, sprints, and sprint issue listings

• 🔐 Secure Authentication: Uses Jira API tokens for secure access

• 🎯 Structured Data: Returns both human-readable and structured JSON data

• 🚀 Claude Desktop Integration: Seamlessly works with Claude Desktop via MCP protocol

Prerequisites

• Node.js (v18 or higher)

• Claude Desktop application

• Jira instance with API access

• Jira API token

Installation

1. Clone the repository

   git clone https://github.com/imrnbeg/jira-mcp.git cd jira-mcp

2. Install dependencies

   npm install

3. Build the project

   npm run build

Configuration

1. Create Environment File

Create a .env file in the project root with your Jira credentials:

How to get your Jira API token:

1. Go to Atlassian Account Settings

2. Click "Create API token"

3. Give it a label (e.g., "MCP Server")

4. Copy the generated token

2. Update Server Path (Important!)

⚠️ CRITICAL: You must update the .env file path in the server code to match your system.

Edit src/server.ts and update line 8:

For different systems:

• macOS/Linux: /full/path/to/your/jira-mcp/.env

• Windows: C:\\full\\path\\to\\your\\jira-mcp\\.env

3. Rebuild After Path Update

After updating the path, rebuild the project:

Claude Desktop Setup

1. Locate Claude Desktop Config

macOS:

Windows:

2. Add MCP Server Configuration

Add this configuration to your Claude Desktop config file:

⚠️ Update the paths to match your system:

• Replace /full/path/to/your/jira-mcp with your actual project path

• Use forward slashes (/) even on Windows

3. Restart Claude Desktop

After updating the configuration, completely quit and restart Claude Desktop.

Usage

Once configured, you can use these example prompts in Claude Desktop:

Basic Issue Lookup

Detailed Issue Information

Multiple Issues

Issue Status Check

Available Tools

get_jira_issue

Fetches detailed information about a Jira issue.

Parameters:

• issueKey (string): The Jira issue key (e.g., PROJ-123, TASK-456)

Returns:

• Issue summary, description, status, assignee, reporter

• Priority, issue type, creation and update dates

• Direct link to the issue in Jira

• Structured JSON data for programmatic access

list_jira_projects

List accessible Jira projects with pagination and optional search query.

Parameters:

• query (string, optional): Search by key/name

• startAt (number, optional): Pagination start

• maxResults (number, optional): Page size (1-100)

get_jira_project

Get full metadata for a Jira project by key or ID.

Parameters:

• projectIdOrKey (string): Project key or ID

get_project_statuses

Get available statuses for each issue type in a project.

Parameters:

• projectIdOrKey (string): Project key or ID

search_jira_issues

Search issues using JQL with pagination and field selection.

Parameters:

• jql (string): JQL query

• startAt (number, optional): Pagination start

• maxResults (number, optional): Page size (1-100)

• fields (string, optional): Comma-separated fields

list_project_issues

List issues in a specific project with optional extra JQL.

Parameters:

• projectKey (string): Project key

• jqlTail (string, optional): Extra JQL (e.g., AND status="In Progress")

• startAt (number, optional): Pagination start

• maxResults (number, optional): Page size (1-100)

get_jira_issue_comments

Retrieve comments for a Jira issue.

Parameters:

• issueIdOrKey (string): Issue key or ID

• startAt (number, optional): Pagination start

• maxResults (number, optional): Page size (1-100)

list_boards

List Jira boards with optional filters.

Parameters:

• type ("scrum"|"kanban", optional): Board type

• projectKeyOrId (string, optional): Filter by project

• startAt (number, optional): Pagination start

• maxResults (number, optional): Page size (1-100)

list_board_sprints

List sprints on a board.

Parameters:

• boardId (number): Board ID

• state ("active"|"future"|"closed", optional): Sprint state

• startAt (number, optional): Pagination start

• maxResults (number, optional): Page size (1-100)

list_sprint_issues

List issues in a sprint with pagination.

Parameters:

• sprintId (number): Sprint ID

• startAt (number, optional): Pagination start

• maxResults (number, optional): Page size (1-100)

• jql (string, optional): Additional JQL filter

Example Prompts

Use these prompts in Claude Desktop to leverage the tools:

Project discovery

Issue search and browsing

Agile views

Development

Running in Development Mode

Building for Production

Type Checking

Troubleshooting

Server Not Loading Environment Variables

1. Check the path in - Make sure it points to your actual .env file location

2. Rebuild the project after changing the path:

   npm run build

3. Verify and contains valid credentials

Claude Desktop Not Connecting

1. Check the config file paths - Ensure all paths in claude_desktop_config.json are correct

2. Restart Claude Desktop completely

3. Check Claude Desktop logs for connection errors

Jira API Errors

1. Verify your API token is valid and not expired

2. Check your Jira URL format (should include https://)

3. Ensure your account has access to the Jira instance

Project Structure

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Test thoroughly

5. Submit a pull request

License

ISC License

Support

For issues and questions:

1. Check the troubleshooting section above

2. Review the MCP documentation

3. Open an issue on GitHub

Happy Jira integration with Claude! 🚀