Jira MCP server for AI agents

This MCP server integrates Jira with AI assistants like Claude, allowing interaction with Jira data and functions through the Model Context Protocol.

Installation

# Clone the repository
git clone https://github.com/samuelrizzo/jira-mcp-server.git
cd jira-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Configuration

MCP Server Setup

Add this configuration to your cursor/windsurf mcp settings file:

{
  "mcpServers": {
    "jira-mcp": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "JIRA_HOST": "your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Getting Jira API Access

Generate a Jira API token:
- Visit Atlassian Account Settings
- Click "Create API Token"
- Name your token and click "Create"
- Copy the generated token
Make note of:
- Your Jira host URL (e.g., your-domain.atlassian.net)
- Email associated with your Atlassian account
Add these credentials to your MCP server configuration as shown above.

Available Tools

List Projects

Lists all accessible Jira projects.

Parameters:

jiraHost: Your Jira domain
email: Your Jira email
apiToken: Your Jira API token

Get Issue Details

Retrieves comprehensive information about a specific issue.

Parameters:

issueKey: Jira issue key (e.g., 'PROJECT-123')
jiraHost: Your Jira domain
email: Your Jira email
apiToken: Your Jira API token

Search Issues

Searches for issues in a project with optional assignee filtering.

Parameters:

projectKey: Jira project key
assigneeName: (Optional) Filter by assignee
jiraHost: Your Jira domain
email: Your Jira email
apiToken: Your Jira API token

List Project Members

Shows all members of a specified project.

Parameters:

projectKey: Jira project key
jiraHost: Your Jira domain
email: Your Jira email
apiToken: Your Jira API token

Check User Issues

Verifies project membership and lists assigned issues for a user.

Parameters:

projectKey: Jira project key
userName: User's display name
jiraHost: Your Jira domain
email: Your Jira email
apiToken: Your Jira API token

Create Issue

Creates a new issue with specified details.

Parameters:

projectKey: Jira project key
summary: Issue title
description: Detailed description
issueType: (Optional) Type of issue (default: 'Task')
assigneeName: (Optional) Assignee's display name
reporterName: (Optional) Reporter's display name
sprintId: (Optional) Sprint ID
jiraHost: Your Jira domain
email: Your Jira email
apiToken: Your Jira API token

List Sprints

Lists sprints with filtering options.

Parameters:

boardId: (Optional) Board ID to filter sprints
projectKey: (Optional) Project key for associated sprints
state: (Optional) Sprint state (active, future, closed, all)
jiraHost: Your Jira domain
email: Your Jira email
apiToken: Your Jira API token

Usage Examples

You can ask Claude to perform tasks like:

"List all Jira projects in PROJECT"
"Get details for issue PROJECT-123"
"Search for issues assigned to John in PROJECT"
"List all members of PROJECT"
"Check what issues are assigned to Jane in PROJECT"
"Create a new bug issue titled 'Login page error' in PROJECT"
"List active sprints for PROJECT"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "jira-mcp" '{"command":"node","args":["./dist/index.js"],"env":{"JIRA_HOST":"your-domain.atlassian.net","JIRA_EMAIL":"[email protected]","JIRA_API_TOKEN":"your-api-token-here"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "jira-mcp": {
            "command": "node",
            "args": [
                "./dist/index.js"
            ],
            "env": {
                "JIRA_HOST": "your-domain.atlassian.net",
                "JIRA_EMAIL": "[email protected]",
                "JIRA_API_TOKEN": "your-api-token-here"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "jira-mcp": {
            "command": "node",
            "args": [
                "./dist/index.js"
            ],
            "env": {
                "JIRA_HOST": "your-domain.atlassian.net",
                "JIRA_EMAIL": "[email protected]",
                "JIRA_API_TOKEN": "your-api-token-here"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect