jd-mcp — MCP Server for Jira

An MCP (Model Context Protocol) server that gives AI assistants like Claude the ability to read, create, and manage Jira issues — with a human-in-the-loop approval workflow. All proposed changes are queued for review before being applied to Jira.

Prerequisites

This package requires the AgentGate for Jira Forge app to be installed on your Jira Cloud instance. The app provides the backend API, token management, and the human approval workflow.

Install it from the Atlassian Marketplace.

Install

npx (zero-install)

npx @orbiscend/jd-mcp

npm (global)

npm install -g @orbiscend/jd-mcp

Docker

docker pull orbiscend/jd-mcp:latest

Configuration

You need three environment variables:

| Variable | Description | |----------|-------------| | JD_ENDPOINT | Your Forge webtrigger URL | | JD_TOKEN | Your API token | | JD_PROJECT | Default Jira project key (optional, acts as fallback) |

Optional:

| Variable | Description | |----------|-------------| | JD_TIMEOUT | Request timeout in ms (default 30000) | | JD_MAX_RETRIES | Max retries for rate limits (default 3) |

The server also reads from config files if present: .jira-for-ai/config.json (project) or ~/.jira-for-ai/config.json (global).

Setup

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Using npx:

{
  "mcpServers": {
    "agentgate-for-jira": {
      "command": "npx",
      "args": ["-y", "@orbiscend/jd-mcp"],
      "env": {
        "JD_ENDPOINT": "https://your-forge-app.atlassian.net/x/...",
        "JD_TOKEN": "your-token",
        "JD_PROJECT": "PROJ"
      }
    }
  }
}

Using global install:

{
  "mcpServers": {
    "agentgate-for-jira": {
      "command": "jd-mcp",
      "env": {
        "JD_ENDPOINT": "https://your-forge-app.atlassian.net/x/...",
        "JD_TOKEN": "your-token",
        "JD_PROJECT": "PROJ"
      }
    }
  }
}

Using Docker:

{
  "mcpServers": {
    "agentgate-for-jira": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "JD_ENDPOINT",
        "-e", "JD_TOKEN",
        "-e", "JD_PROJECT",
        "orbiscend/jd-mcp:latest"
      ],
      "env": {
        "JD_ENDPOINT": "https://your-forge-app.atlassian.net/x/...",
        "JD_TOKEN": "your-token",
        "JD_PROJECT": "PROJ"
      }
    }
  }
}

Claude Code

Add to your project's .claude/settings.json or global ~/.claude.json:

{
  "mcpServers": {
    "agentgate-for-jira": {
      "command": "npx",
      "args": ["-y", "@orbiscend/jd-mcp"],
      "env": {
        "JD_ENDPOINT": "https://your-forge-app.atlassian.net/x/...",
        "JD_TOKEN": "your-token",
        "JD_PROJECT": "PROJ"
      }
    }
  }
}

Other MCP Clients

Any MCP-compatible client can use this server. It communicates over stdio. Run it with the environment variables set and connect via stdin/stdout.

Available Tools (13)

| Category | Tools | |----------|-------| | Session | prime — project status, in-progress issues, pending changes | | Reading | issues_list, issues_show, issues_children, issues_context, issues_transitions | | Writing | changes_create, comment, changes_update, changes_cancel | | Managing | changes_list, changes_show, workflow_describe |

All write operations create pending changes that require human approval before being applied to Jira.

Resources

• jira://quickstart — Quick reference for using Jira tools
• jira://workflow/{project_key} — Dynamic project workflow data

Troubleshooting

"Missing endpoint/token/project" — Ensure all required environment variables are set in your MCP client configuration.

Connection timeout — Check that the Forge app is deployed and the endpoint URL is correct.

Authentication failed — Your token may be expired. Generate a new one via jd init --rotate.

Links

• Orbiscend
• AgentGate on Atlassian Marketplace