mcp-bitbucket-ts

A minimal Model Context Protocol server for Atlassian Bitbucket Cloud, written in TypeScript. It exposes five generic tools that pass through to the Bitbucket 2.0 REST API, plus a git clone helper — connecting AI assistants (Claude, Cursor, …) directly to your repositories and pull requests.

Tools

| Tool | Maps to | | ----------- | ------------------------------------ | | bb_get | GET {path} — read any endpoint | | bb_post | POST {path} — create a resource | | bb_put | PUT {path} — replace a resource | | bb_patch | PATCH {path} — partial update | | bb_delete | DELETE {path} — remove a resource | | bb_clone | git clone a repo over HTTPS |

path is relative to https://api.bitbucket.org/2.0, e.g. user, repositories/{workspace}, or repositories/{workspace}/{repo_slug}/pullrequests. The read/write tools accept an optional filter — a JMESPath expression applied to the JSON response to trim the payload.

Requirements

• Node.js 24+
• Node.js 24+
• A Bitbucket API token — Atlassian account → Security → API tokens. Auth is HTTP Basic, using your account email plus the token.

Setup

Log in once. The token is verified against the API and then stored in your OS keychain — Keychain on macOS, libsecret on Linux, Credential Manager on Windows:

npx mcp-bitbucket-ts login

Atlassian account email: [email protected]
Bitbucket API token (input hidden):
Verifying... authenticated as Your Name
Saved to the OS keychain.

Then point your MCP client at the server. No credentials in the config file:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "mcp-bitbucket-ts@latest"]
    }
  }
}

That's the whole setup. Restart the client to load it. Pin a version ([email protected]) instead of @latest if you want reproducible, review-before-upgrade behaviour.

Other commands:

| Command | Does | | --- | --- | | login | Prompt for credentials, verify them, store them | | logout | Delete the stored credentials | | status | Show which credentials are in effect, and where they came from |

login is scriptable too: pass --username [email protected] --token <token>, or pipe the token on stdin:

echo "$TOKEN" | npx mcp-bitbucket-ts login --username [email protected]

Run from GitHub without publishing to npm — npx can execute the repo directly (it builds via the prepare script):

"args": ["-y", "github:MobarakHsn/mcp-bitbucket-ts"]

Credentials without a keychain

CI runners and containers have no keychain. Two environment variables cover that, and both take precedence over stored credentials so you can override without clearing them:

| Variable | Purpose | | --- | --- | | BITBUCKET_USERNAME | Atlassian account email | | BITBUCKET_API_TOKEN | The API token itself | | BITBUCKET_API_TOKEN_CMD | A command whose stdout is the token — wins over BITBUCKET_API_TOKEN |

BITBUCKET_API_TOKEN_CMD exists for external password managers. It runs through the platform shell, so pipelines work, and trailing newlines are trimmed:

"env": {
  "BITBUCKET_USERNAME": "[email protected]",
  "BITBUCKET_API_TOKEN_CMD": "pass show bitbucket/api-token"
}

The command must be non-interactive. A locked store that prompts for a passphrase hangs until the 15s timeout and the server exits with an error. On failure only the exit status and the command string are reported — the command's own output is discarded so a partial secret cannot land in logs. For that reason, do not inline the secret into the command itself.

Resolution order is BITBUCKET_API_TOKEN_CMD, then BITBUCKET_API_TOKEN, then the keychain. mcp-bitbucket-ts status prints which one is in effect, and login warns if an env var would shadow what it just saved.

Optional: BITBUCKET_API_BASE_URL (defaults to https://api.bitbucket.org/2.0).

Local development

npm install
npm run build      # tsc -> dist/
npm run dev        # run from source via tsx

Quick stdio smoke test (lists the tools without a full client):

BITBUCKET_USERNAME=x BITBUCKET_API_TOKEN=y node dist/index.js
# then feed it JSON-RPC: initialize, then tools/list

Or use the official inspector: npx @modelcontextprotocol/inspector node dist/index.js.

Publishing

npm run build
npm publish        # prepublishOnly rebuilds; only dist/ + README + LICENSE ship

Security notes

• Credentials are resolved at startup from the OS keychain or the environment, and never leave your machine except as HTTPS requests to bitbucket.org.
• login stores the token under service mcp-bitbucket-ts, encrypted at rest by the OS and unlocked with your login session. Nothing is written in plaintext.
• bb_clone injects the token into the git remote URL for a single invocation and redacts it from any surfaced output/error.
• bb_post / bb_put / bb_patch / bb_delete mutate your Bitbucket. Scope the API token to the minimum permissions you need.

Layout

src/
  index.ts        # server + 6 tool registrations (stdio transport)
  cli.ts          # login / logout / status subcommands
  credentials.ts  # keychain storage + credential resolution order
  bitbucket.ts    # REST client (basic auth) + git clone helper

License

ISC