jira-bitbucket-mcp

Two Model Context Protocol servers in one npm package, for self-hosted Atlassian instances:

These are Server / Data Center APIs. The Jira Cloud v3 API with accountId-based fields is not supported, and neither is the Bitbucket Cloud 2.0 API. If you are on Atlassian Cloud, use a Cloud-specific MCP server instead.

Both servers speak MCP over stdio and work with any MCP client (VS Code, Claude Desktop, Cursor, Zed, custom agents, …).

Requirements

• Node.js >= 18.17

• A Jira and/or Bitbucket Server / Data Center instance reachable over HTTPS

• A personal access token for each instance

Related MCP server: Atlassian Data Center MCP

Getting tokens

• Jira: avatar → Profile → Personal Access Tokens → Create token

• Bitbucket: avatar → Manage account → Personal Access Tokens → Create token (needs Repository read, plus write for PR actions)

Use your own token so actions are attributed to you.

Usage

No install needed — run either server with npx:

JIRA_BASE_URL=https://jira.example.com JIRA_PAT=xxx npx -y jira-bitbucket-mcp jira

Or install globally, which puts jira-bitbucket-mcp on your PATH:

npm install -g jira-bitbucket-mcp

VS Code

Add to .vscode/mcp.json (workspace) or your user mcp.json:

{
  "inputs": [
    { "id": "jira-pat", "type": "promptString", "description": "Jira PAT", "password": true },
    { "id": "bitbucket-token", "type": "promptString", "description": "Bitbucket token", "password": true }
  ],
  "servers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "jira-bitbucket-mcp", "jira"],
      "env": {
        "JIRA_BASE_URL": "https://jira.example.com",
        "JIRA_PAT": "${input:jira-pat}",
        "JIRA_DEFAULT_PROJECT": "PROJ"
      }
    },
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "jira-bitbucket-mcp", "bitbucket"],
      "env": {
        "BITBUCKET_BASE_URL": "https://bitbucket.example.com",
        "BITBUCKET_TOKEN": "${input:bitbucket-token}",
        "BITBUCKET_DEFAULT_PROJECT": "PROJ",
        "BITBUCKET_DEFAULT_REPO": "my-repo"
      }
    }
  }
}

Then: Command Palette → MCP: List Servers → start jira and/or bitbucket. You are prompted for each token once and VS Code stores it in the OS secret store.

Claude Desktop and other clients

In claude_desktop_config.json, or the equivalent config of your client:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "jira-bitbucket-mcp", "jira"],
      "env": {
        "JIRA_BASE_URL": "https://jira.example.com",
        "JIRA_PAT": "your-token"
      }
    }
  }
}

Environment variables

Jira

Bitbucket

Tools

Jira

Read: jira_myself, jira_search (JQL), jira_get_issue, jira_list_projects, jira_get_transitions, jira_get_create_meta, jira_list_fields, jira_list_attachments, jira_get_attachment, jira_list_worklogs, jira_list_link_types, jira_list_watchers, plus jira_list_boards, jira_list_sprints and jira_get_sprint_issues (need Jira Software).

Write: jira_create_issue, jira_update_issue, jira_add_comment, jira_update_comment, jira_transition_issue, jira_assign_issue, jira_add_worklog, jira_link_issues, jira_add_watcher, jira_remove_watcher, jira_add_attachment, plus jira_delete_issue, jira_delete_comment and jira_delete_attachment (opt-in).

Bitbucket

Read: bitbucket_myself, bitbucket_list_repos, bitbucket_list_pull_requests, bitbucket_get_pull_request, bitbucket_get_pull_request_diff, bitbucket_list_pull_request_comments, bitbucket_list_pull_request_changes, bitbucket_get_build_status, bitbucket_list_branches, bitbucket_list_commits, bitbucket_get_file, bitbucket_browse_files, bitbucket_search_code (needs the Data Center built-in code search).

Write: bitbucket_create_pull_request, bitbucket_update_pull_request, bitbucket_add_pull_request_comment (general, inline or reply), bitbucket_update_pull_request_comment (edit, resolve, task), bitbucket_review_pull_request, plus bitbucket_merge_pull_request and bitbucket_decline_pull_request (opt-in via BITBUCKET_ALLOW_MERGE) and bitbucket_delete_pull_request_comment (opt-in via BITBUCKET_ALLOW_DELETE).

Responses are trimmed projections; several read tools accept raw: true for the full payload.

Safety

• Destructive operations are opt-in: JIRA_ALLOW_DELETE, BITBUCKET_ALLOW_DELETE and BITBUCKET_ALLOW_MERGE are off by default.

• JIRA_READ_ONLY=1 / BITBUCKET_READ_ONLY=1 register the read tools only — a good default for exploratory agents.

• Tokens are never logged and are stripped from error messages before they are returned.

• *_BASE_URL must be https unless it points at localhost.

• Attachments are only written to and uploaded from JIRA_ATTACHMENTS_DIR; paths outside it are rejected. jira_get_attachment also works in read-only mode because it only writes to that local directory.

Notes

• jira_assign_issue and Bitbucket reviewer lists take Server usernames / user slugs, not email addresses.

• Issue keys look like PROJ-1234; pull requests are addressed by project key + repository slug + numeric id.

Development

git clone https://github.com/heminei/jira-bitbucket-mcp.git
cd jira-bitbucket-mcp
npm install
npm run build

Layout:

src/cli.ts      bin entrypoint, dispatches to the jira or bitbucket server
src/shared/     env parsing, HTTP client with bearer auth + token redaction, result formatting
src/jira/       Jira config, client, tools, entrypoint      -> dist/jira/index.js
src/bitbucket/  Bitbucket config, client, tools, entrypoint -> dist/bitbucket/index.js

Debug with the MCP inspector:

JIRA_BASE_URL=... JIRA_PAT=... npm run inspect:jira
BITBUCKET_BASE_URL=... BITBUCKET_TOKEN=... npm run inspect:bitbucket

Issues and pull requests are welcome.

License

MIT © Martin Bratvanov