Jira Data Center MCP Wrapper

A thin cross-platform wrapper that makes the community mcp-jira-stdio MCP server talk to Jira Data Center / Server instances that only expose the REST API v2.

It does not re-implement a Jira MCP server. It auto-detects the API-version mismatch at startup and patches the compiled mcp-jira-stdio bundle from /rest/api/3 to /rest/api/2, so Claude Code (or any MCP client) can manage issues on a self-hosted Jira.

2026 context: this was written as a pragmatic in-company fix when the mainstream mcp-jira-stdio only targeted Jira Cloud's API v3 and few Data Center options existed. The field has since matured — if you're starting fresh, you may prefer purpose-built Data Center servers such as williace/jira-dc-mcp-server or sooperset/mcp-atlassian. Atlassian's official MCP server remains Cloud-only and does not support Data Center.

Background

• Company runs Jira Data Center on a private domain.

• Team wanted to drive Jira through Claude Code via MCP.

• The go-to community server at the time, mcp-jira-stdio, hardcoded requests to the Jira REST API v3 path (/rest/api/3/).

• REST API v3 is Cloud-only. Data Center / Server stop at API v2.

• Result: every mcp-jira-stdio call returned 404 / not found against the internal instance.

Related MCP server: jira-mcp

Diagnosis

Instead of writing a server from scratch, the fix targeted the real cause:

1. Read the upstream compiled bundle at node_modules/mcp-jira-stdio/dist/index.js.

2. Located the hardcoded base path: BASE_PATH: "/rest/api/3" (plus per-request URL templates building .../rest/api/3/...).

3. Confirmed v2 is fully compatible for the operations the server exposes (issue read/write, JQL search, project/issue-type/priority metadata, comments, links, subtasks).

Fix

Two cross-platform scripts, no build step:

The wrapper (not a postinstall hook) is the entry point because a hook is one-shot and fragile across npm install / lockfile resets; the wrapper repairs on every launch, cross-platform (.sh for macOS/Linux, .bat for Windows), and is safe to share with the team.

Result

• Claude Code connects to the internal Jira Data Center instance through the standard mcp-jira-stdio tool surface (jira_get_issue, jira_search_issues, jira_create_issue, jira_update_issue, jira_add_comment, jira_create_subtask, jira_create_issue_link, …).

• The fix survives dependency reinstalls automatically.

• A team member on Windows or macOS needs no extra steps.

Usage

1. Install

cd /path/to/jira-mcp-studio-bundle
npm install

mcp-jira-stdio is the only runtime dependency (see package.json).

2. Configure Claude Code

Point the MCP server at the wrapper script for your platform (absolute paths):

{
  "mcpServers": {
    "jira": {
      "command": "/absolute/path/to/jira-mcp-studio-bundle/mcp-jira-wrapper.sh", // or mcp-jira-wrapper.bat on Windows
      "args": [],
      "cwd": "/absolute/path/to/jira-mcp-studio-bundle",
      "env": {
        "JIRA_BASE_URL": "https://your-jira-dc-instance.example.com",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-token-or-password"
      }
    }
  }
}

• macOS/Linux global config: ~/.claude.json or ~/.config/claude-code/config.json.

• Windows global config: %APPDATA%\claude-code\config.json — use the .bat, double backslashes in paths.

• Authentication: for Data Center, an email + API token works, or a server-side Personal Access Token. Ask your Jira admin if unsure.

3. Verify

# Manual connectivity check (v2 endpoint)
curl -u "your-email:your-token" "https://your-jira-dc-instance.example.com/rest/api/2/myself"

# Confirm the patch is in place (expect api/2, no api/3)
grep -c "rest/api/3" node_modules/mcp-jira-stdio/dist/index.js   # → 0
grep -c "rest/api/2" node_modules/mcp-jira-stdio/dist/index.js   # → >0

Restart Claude Code to load the server.

How the fix works (for reviewers)

mcp-jira-stdio builds request URLs from a BASE_PATH constant plus URL templates that also carry /rest/api/3/. apply-fix rewrites both so every outbound call targets API v2. For the operations used here the v2 and v3 payloads/responses do not differ, so a path swap is behavior-preserving against a v2-only instance.

Files

├── package.json             # dependency: mcp-jira-stdio
├── mcp-jira-wrapper.sh      # macOS/Linux entry: detect + patch + exec
├── mcp-jira-wrapper.bat     # Windows entry: detect + patch + exec
├── apply-fix.sh             # macOS/Linux one-shot patch
├── apply-fix.bat            # Windows one-shot patch
├── README.md                # this file
└── README-zh.md             # 中文说明

Troubleshooting

• Permission denied (macOS/Linux): chmod +x mcp-jira-wrapper.sh apply-fix.sh.

• Patch not applied: run ./apply-fix.sh (or apply-fix.bat) manually, then check the grep counts above.

• 401: credentials wrong or expired — verify via the curl check. Test a PAT if email+token is rejected.

• Windows '.' 不是内部或外部命令: you invoked the .sh — use mcp-jira-wrapper.bat.

Limitations / Alternatives

• This package is a compatibility shim around a third-party server, not a Jira MCP implementation. You inherit mcp-jira-stdio's tool set and maintenance.

• If you need more (Agile boards/sprints, attachments, richer auth), evaluate a dedicated Data Center MCP server — see the 2026 note at the top.

License

Shell scripts and docs in this repo are provided under the MIT License. The mcp-jira-stdio dependency keeps its own license — see its repository.