<div align="center">
  <img src="assets/jira-logo.png" alt="Jira Logo" width="200"/>
</div>

# Jira MCP Server

A Model Context Protocol (MCP) server for interacting with Atlassian Jira. Connect AI assistants like Claude, Cursor AI, and others directly to your Jira projects, issues, and workflows.

## Prerequisites

1. Node.js (version 18 or higher)
2. Atlassian Jira account with:
   - API token - Generated from [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
   - Site name - Your Jira organization name (e.g., `mycompany` for `mycompany.atlassian.net`)

## Installation

### Via npm (recommended)

```bash
npm install -g jira-mcp-server
```

### From Source

1. Install dependencies: `npm install`
2. Build the project: `npm run build`
3. Configure your MCP client (see below)

## Configuration

### For Cursor Users

Add this to your Cursor MCP configuration (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "Jira MCP": {
      "command": "node",
      "args": [
        "/path/to/mcp-server-atlassian-jira/dist/index.js"
      ],
      "env": {
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}
```

Restart Cursor to activate.

### For Claude Desktop Users

Add this to your Claude configuration file (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": [
        "/path/to/mcp-server-atlassian-jira/dist/index.js"
      ],
      "env": {
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}
```

Restart Claude Desktop to activate.

## Available Tools

- `jira_get` - Read data from any Jira API endpoint
- `jira_post` - Create resources (issues, comments, etc.)
- `jira_put` - Replace resources
- `jira_patch` - Partially update resources
- `jira_delete` - Delete resources
- `health_check` - Verify server configuration and connectivity

## Common Use Cases

Ask your AI assistant:
- *"List all projects I have access to"*
- *"Show me issues assigned to me that are in progress"*
- *"Find all high priority issues in the DEV project"*
- *"Get full details about issue PROJ-456 including comments"*
- *"Add a comment to PROJ-456: 'Code review completed'"*
- *"Create a new bug in the MOBILE project"*

## Troubleshooting

### Authentication Issues

1. Verify your API token is active at [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Check your site name format: `https://mycompany.atlassian.net` → site name is `mycompany`
3. Test credentials: `node dist/index.js get --path "/rest/api/3/myself"`

### Common Errors

- **403 Forbidden**: Check API token permissions
- **404 Not Found**: Verify project keys and issue IDs are correct
- **No results**: Try broader search criteria or validate JQL syntax

### Integration Issues

- **Cursor**: Restart Cursor after updating `~/.cursor/mcp.json`
- **Claude Desktop**: Restart Claude Desktop after updating config file

## FAQ

**What permissions do I need?**  
Your Atlassian account needs access to Jira with appropriate project permissions.

**Does this work with Jira Server?**  
Currently supports Jira Cloud only.

**Is my data secure?**  
Yes! This tool runs entirely on your local machine and uses your own Jira credentials.