Jira MCP Server

A Model Context Protocol (MCP) server for Jira Cloud that enables AI assistants to interact with Jira issues.

Features

| Tool | Description | |------|-------------| | create_issue | Create a new Jira issue (Story, Bug, Task, Epic, etc.) | | get_issue | Get detailed information about a specific Jira issue | | list_issues | Search for issues using JQL (Jira Query Language) | | get_issue_fields | Get all fields (including custom fields) for an issue | | update_issue | Update an existing issue (summary, description, assignee, priority, labels, custom fields) | | delete_issue | Delete a Jira issue by key or ID (with optional subtask deletion) | | add_comment | Add a comment to a Jira issue | | get_transitions | Get available status transitions for an issue | | transition_issue | Transition an issue to a new status |

Prerequisites

• Node.js 18+ or Bun runtime
• Jira Cloud account with API access
• API token from Atlassian API Tokens

Installation

The easiest way to use this MCP server is via npx or bunx - no installation required! Just configure your MCP client as shown below.

If you prefer to install globally:

# Using npm
npm install -g @carmeloricarte/jira-mcp-server

# Using Bun
bun install -g @carmeloricarte/jira-mcp-server

Environment Variables

Important: You do NOT need to set environment variables at the system or user level. The MCP client will pass them to the server process when it starts. Just configure them in the env object of your MCP configuration.

| Variable | Description | Example | |----------|-------------|---------| | JIRA_HOST | Your Jira Cloud domain (without https://) | your-company.atlassian.net | | JIRA_EMAIL | Email associated with your Atlassian account | [email protected] | | JIRA_API_TOKEN | API token generated from Atlassian | ATATT3xF... |

MCP Client Configuration

Note: All examples below use npx (Node.js). If you prefer Bun, replace "command": "npx" with "command": "bunx" and remove the "-y" from args.

⚠️ Windows Configuration

On Windows, you must wrap npx or bunx commands with cmd /c. Use this format:

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@carmeloricarte/jira-mcp-server"]
}

Or with Bun:

{
  "command": "cmd",
  "args": ["/c", "bunx", "@carmeloricarte/jira-mcp-server"]
}

Important: The package name must always be the last argument in the args array.

Claude Code

Config file location:

• macOS/Linux: ~/.claude/settings.json
• Windows: %USERPROFILE%\.claude\settings.json

{
  "mcpServers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@carmeloricarte/jira-mcp-server"],
      "env": {
        "JIRA_HOST": "your-company.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

VS Code (Copilot MCP Extension)

Config file location:

• macOS/Linux: ~/.vscode/mcp.json or workspace .vscode/mcp.json
• Windows: %USERPROFILE%\.vscode\mcp.json or workspace .vscode\mcp.json

{
  "servers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@carmeloricarte/jira-mcp-server"],
      "env": {
        "JIRA_HOST": "your-company.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Cursor

Config file location:

• macOS: ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json
• Windows: %APPDATA%\Cursor\User\globalStorage\cursor.mcp\mcp.json

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@carmeloricarte/jira-mcp-server"],
      "env": {
        "JIRA_HOST": "your-company.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Zed

Config file location:

• macOS: ~/.config/zed/settings.json
• Windows: %APPDATA%\Zed\settings.json

{
  "language_models": {
    "mcp_servers": {
      "jira": {
        "command": "npx",
        "args": ["-y", "@carmeloricarte/jira-mcp-server"],
        "env": {
          "JIRA_HOST": "your-company.atlassian.net",
          "JIRA_EMAIL": "[email protected]",
          "JIRA_API_TOKEN": "your-api-token"
        }
      }
    }
  }
}

OpenCode

Config file location:

• macOS/Linux: ~/.config/opencode/config.json
• Windows: %USERPROFILE%\.config\opencode\config.json

{
  "mcp_servers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@carmeloricarte/jira-mcp-server"],
      "env": {
        "JIRA_HOST": "your-company.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Codex (OpenAI CLI)

Config file location:

• macOS/Linux: ~/.codex/config.json
• Windows: %USERPROFILE%\.codex\config.json

{
  "mcpServers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@carmeloricarte/jira-mcp-server"],
      "env": {
        "JIRA_HOST": "your-company.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Windsurf (Codeium)

Config file location:

• macOS: ~/.codeium/windsurf/mcp_config.json
• Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@carmeloricarte/jira-mcp-server"],
      "env": {
        "JIRA_HOST": "your-company.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Tool Examples

Create Issue

Create a new Story in project PROJ with title "Implement user authentication"

Create an Epic in PROJ called "[EPIC] Payment System" with description "Complete payment integration"

Get Issue

Get issue PROJ-123

Search Issues with JQL

Search for issues: project = PROJ AND status = "In Progress"

Update Issue

Update PROJ-123: change priority to High and add labels "urgent", "frontend"

Update the description of PROJ-123 to "Updated requirements..."

Delete Issue

Delete issue PROJ-123

Delete PROJ-456 and all its subtasks

Add Comment

Add comment "Working on this now" to PROJ-123

Transition Issue

Move PROJ-123 to "In Progress"

Development

Clone and install dependencies

git clone https://github.com/carmeloricarte/jira-mcp-server.git
cd jira-mcp-server
bun install

Run tests

bun test

Run tests with coverage

bun test --coverage

Run the server standalone

JIRA_HOST=your-company.atlassian.net \
[email protected] \
JIRA_API_TOKEN=your-token \
bun run start

Troubleshooting

Server not starting

1. Verify Node.js 18+ or Bun is installed: node --version or bun --version
2. Try running manually: npx -y @carmeloricarte/jira-mcp-server or bunx @carmeloricarte/jira-mcp-server
3. Check for any error messages in your MCP client logs

Authentication errors

1. Verify your API token is valid at Atlassian API Tokens
2. Ensure JIRA_HOST does not include https://
3. Verify JIRA_EMAIL matches the email used to generate the token

Empty results from list_issues

The server includes default fields (summary, status, priority, issuetype, assignee, updated). If you need additional fields, pass them in the fields parameter.

Contributing

Contributions are welcome! If you'd like to contribute to this project:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Guidelines

• Follow the existing code style
• Write tests for new features
• Update documentation as needed
• Use Conventional Commits for commit messages

Reporting Issues

Found a bug or have a feature request? Please open an issue with as much detail as possible.

License

MIT