# Jira Data Center MCP Wrapper

A thin cross-platform wrapper that makes the community [`mcp-jira-stdio`](https://github.com/freema/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`](https://github.com/williace/jira-dc-mcp-server) or [`sooperset/mcp-atlassian`](https://github.com/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.

## 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:

| File | Role |
|------|------|
| `apply-fix.sh` / `apply-fix.bat` | Idempotent patch: rewrites `BASE_PATH: "/rest/api/3"` → `BASE_PATH: "/rest/api/2"` and every `/rest/api/3/` → `/rest/api/2/` in the compiled bundle. Backs up the original as `*.backup`. |
| `mcp-jira-wrapper.sh` / `mcp-jira-wrapper.bat` | Runtime guard used as the MCP server command: greps the bundle for a v3 residue on every start, re-applies the fix if a reinstall reset it, then starts the real server. Self-healing. |

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

```bash
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):

```jsonc
{
  "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](https://id.atlassian.com/manage-profile/security/api-tokens) works, or a server-side Personal Access Token. Ask your Jira admin if unsure.

### 3. Verify

```bash
# 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](LICENSE). The `mcp-jira-stdio` dependency keeps its own license — see its repository.