Jira MCP server for AI agents

The Jira MCP Server enables natural language interaction with Jira, allowing you to retrieve information and manage projects through AI tools like Claude Desktop and Cursor. This server acts as a bridge between AI assistants and your Jira instance, making project management tasks more accessible through conversation.

Installation Options

Option 1: Install via Smithery (Recommended for Claude Desktop)

npx -y @smithery/cli install @George5562/Jira-MCP-Server --client claude

Option 2: Manual Installation

Clone the repository:

git clone https://github.com/George5562/Jira-MCP-Server.git
cd Jira-MCP-Server

Install dependencies:
```
npm install
```

Configure environment variables by creating a .env file:

JIRA_HOST=your-instance.atlassian.net
[email protected]
JIRA_API_TOKEN=your-api-token

Build the project:
```
npm run build
```
Start the server:
```
npm start
```

Configuration for AI Tools

Claude Desktop Configuration

Locate your Claude Desktop 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

Add the Jira MCP server to your configuration:

{
  "mcpServers": {
    "jira-server": {
      "name": "jira-server",
      "command": "/path/to/node",
      "args": ["/path/to/jira-server/build/index.js"],
      "cwd": "/path/to/jira-server",
      "env": {
        "JIRA_HOST": "your-jira-instance.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Restart Claude Desktop to apply the changes.

Cursor Configuration

Locate or create Cursor's MCP configuration file:
- Project-specific: .cursor/mcp.json in your project root
- Global: ~/.cursor/mcp.json in your home directory

Add the Jira MCP server configuration:

{
  "mcpServers": {
    "jira-mcp-server": {
      "command": "node",
      "args": [
        "/path/to/your/Jira-MCP-Server/build/index.js"
      ],
      "cwd": "/path/to/your/Jira-MCP-Server",
      "env": {
        "JIRA_HOST": "your-jira-instance.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Restart Cursor to apply the changes.

Using the Server

Available Functionality

The server enables:

Project creation and configuration
Issue and subtask management
Issue linking and dependencies
Automated issue workflows

User Management

Get a user's account ID by email:

{
  email: "[email protected]"
}

Issue Management

Retrieving Issues

// Get all issues in a project
{
  projectKey: "PROJECT"
}

// Get issues with JQL filtering
{
  projectKey: "PROJECT",
  jql: "status = 'In Progress' AND assignee = currentUser()"
}

// Get issues assigned to user
{
  projectKey: "PROJECT",
  jql: "assignee = '[email protected]' ORDER BY created DESC"
}

Creating Issues

// Create a standard issue
{
  projectKey: "PROJECT",
  summary: "Issue title",
  issueType: "Task",
  description: "Detailed description",
  assignee: "accountId",
  labels: ["frontend", "urgent"],
  components: ["ui", "api"],
  priority: "High"
}

// Create a subtask
{
  parent: "PROJECT-123",
  projectKey: "PROJECT",
  summary: "Subtask title",
  issueType: "Subtask",
  description: "Subtask details",
  assignee: "accountId"
}

Updating Issues

// Update issue fields
{
  issueKey: "PROJECT-123",
  summary: "Updated title",
  description: "New description",
  assignee: "accountId",
  status: "In Progress",
  priority: "High"
}

Issue Dependencies

// Create issue link
{
  linkType: "Blocks",
  inwardIssueKey: "PROJECT-124",  // blocked issue
  outwardIssueKey: "PROJECT-123"  // blocking issue
}

Deleting Issues

// Delete single issue
{
  issueKey: "PROJECT-123"
}

// Delete issue with subtasks
{
  issueKey: "PROJECT-123",
  deleteSubtasks: true
}

// Delete multiple issues
{
  issueKeys: ["PROJECT-123", "PROJECT-124"]
}

Description Field Formatting

The description field supports markdown-style formatting:

Use blank lines between paragraphs
Use "- " for bullet points
Use "1. " for numbered lists
Use headers ending with ":" (followed by blank line)

Example:

Task Overview:

This task involves implementing new features:
- Feature A implementation
- Feature B testing

Steps:
1. Design component
2. Implement logic
3. Add tests

Acceptance Criteria:
- All tests passing
- Documentation updated

Example Usage with AI Tools

When interacting with Claude Desktop or Cursor, you can use natural language to work with Jira:

"List all tasks in the PROJECT project"
"Show me all bugs assigned to me"
"Create a new task titled 'Implement login feature' with high priority"
"Update PROJECT-123 to assign it to [email protected] and change status to In Progress"
"Create a subtask for PROJECT-123 to handle error validation"

The AI will use the MCP server to translate these requests into the appropriate Jira API calls and return the results.

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.