bitbucket-dc-mcp

A hardened Model Context Protocol
server that exposes Bitbucket Data Center operations to AI coding
assistants like Claude Code, Claude Desktop, and GitHub Copilot.

On-premise only. This server targets Bitbucket Data Center
(self-hosted), not Bitbucket Cloud. If you run bitbucket.org, use a
Bitbucket Cloud MCP server instead.

Why this exists

Most AI coding assistant integrations assume SaaS deployments: Jira
Cloud, Bitbucket Cloud, GitHub.com. But a large portion of enterprise
development happens behind corporate firewalls, on self-hosted Atlassian
Data Center, where cloud connectors cannot reach.

This project exists to fill that gap. It is a small, auditable, locally
runnable MCP server that an AI assistant can call to interact with an
on-premise Bitbucket Data Center instance, with a security posture that
is suitable for enterprise environments.

What it does

Exposes fourteen tools via the MCP protocol, split into read and write
operations. Write tools are tagged [WRITE] in their description so
the MCP client's human approval UI clearly distinguishes them from
read-only tools.

Read tools

Write tools

Deliberately omitted

merge_pull_request is not exposed by this server, even though the
underlying REST endpoint exists. Merging a PR is the irreversible
operation that moves AI-generated code into the main branch, and the
human review on the PR is the primary checkpoint of the entire
workflow. Exposing a merge tool would let an AI assistant complete the
full clone → branch → commit → push → PR → merge cycle without any
human ever reading the code. See SECURITY.md for the
full rationale.

Security posture

This server is designed to run with enterprise security requirements in
mind. See SECURITY.md for the full threat model.
Highlights:

• No hardcoded credentials. All secrets are read from environment
  variables, which in production should be sourced from a secret store
  (Credential Manager, Azure Key Vault, HashiCorp Vault, etc.).
• Strict input validation. Every tool argument is checked against
  an allowlist regex before being used in git, filesystem, or HTTP
  operations. Path traversal, shell metacharacters, and git option
  injection are all blocked.
• SSRF protection. Only HTTPS URLs to hosts in a configurable
  allowlist are allowed. Redirects are disabled. When the allowlist is
  set explicitly, the base URL host is not silently added to it — an
  explicit allowlist is respected exactly.
• Workspace confinement. All repo paths are resolved and checked to
  stay within the configured workspace directory.
• Timeout enforcement. Every subprocess and HTTP call has a
  configurable timeout; no operation can block indefinitely.
• Token never persisted. The Bitbucket token is passed to git only
  via ephemeral http.extraheader arguments, never written to
  .git/config or URLs.
• Structured audit log. Every tool invocation emits a JSON record
  with timestamp, agent_id, session_id, tool_invoked,
  parameters_used, response_summary, user_id, outcome, and
  error_type, suitable for forwarding to a SIEM.
• Automatic secret redaction in both operational and audit logs.
• No merge tool to preserve the human review gate on pull requests.

Installation

pip install bitbucket-dc-mcp

Requires Python 3.10 or newer and git available on PATH.

Configuration

Configuration is entirely via environment variables. None of them are
committed anywhere by the server itself.

Client configuration

Add the server to your MCP client configuration. For Claude Desktop,
edit claude_desktop_config.json (path varies by OS). Example:

{
  "mcpServers": {
    "bitbucket-dc": {
      "command": "bitbucket-dc-mcp",
      "env": {
        "BITBUCKET_BASE_URL": "https://bitbucket.example.com",
        "BITBUCKET_TOKEN": "${SECRET:bitbucket_token}",
        "BITBUCKET_USERNAME": "your.username",
        "BITBUCKET_DEFAULT_PROJECT": "MYPROJ",
        "BITBUCKET_WORKSPACE": "/path/to/workspace",
        "BITBUCKET_ALLOWED_HOSTS": "bitbucket.example.com"
      }
    }
  }
}

Never commit real tokens to this file. In production, use your
operating system's secret store and reference the secret via a
placeholder that your client resolves at launch. See SECURITY.md.

The ${SECRET:...} syntax shown above is illustrative; the actual
mechanism depends on your MCP client. Some clients read env vars from
the process environment (set them before launching the client); others
support explicit secret-store integration. Check your client's docs.

See examples/mcp_config_generic.json for a complete template.

Usage

Once configured, restart your MCP client and ask the assistant to
perform Bitbucket operations:

"Clone the repository my-service and show me the contents of
src/main.py."

"List the files in the src/ directory of my-service at branch
develop."

"Show me the open pull requests on my-service, then get the diff
of PR #123 and summarize what it changes."

"Create a branch feature/fix-login off master, commit the changes
I'm about to show you, push it, and open a pull request titled 'Fix
login bug'."

"Reply to the comments on PR #456 with clarifications on the
performance concerns raised."

The assistant will invoke the appropriate tools. Your MCP client will
show a per-tool approval dialog before each invocation; do not
disable these approvals in production.

Development

git clone https://github.com/inkman97/bitbucket-dc-mcp
cd bitbucket-dc-mcp
pip install -e .[dev]
pytest

The test suite has 73 tests covering input validation, config loading,
logging and secret redaction, git runner, and HTTP client SSRF
protection. All tests pass without network access or a real Bitbucket
instance.

Limitations and design decisions

No OAuth. Bitbucket Data Center does not support OAuth 2.0 for
REST API client authentication. This server uses an HTTP Access Token
(Bearer), which must be sourced from a secret store in production. If
your security policy mandates OAuth, this server may not meet your
requirements literally, but see SECURITY.md for the
compensating controls.

Stdio transport only. The server runs as a local subprocess of the
MCP client via stdio. It does not expose an HTTP endpoint, which means
there is no network attack surface to worry about, but also means it
cannot be shared between multiple users. Each developer runs their own
instance.

Bitbucket Data Center only. The REST API calls use /rest/api/1.0/
and the clone URL pattern /scm/{project_lower}/{repo}.git specific to
Data Center. For Bitbucket Cloud, use a different server.

No merge operation. Pull requests are created via this server but
must be merged manually through the Bitbucket UI after human review.
This is a deliberate design choice to preserve the review gate. See the
"Deliberately omitted" section above.

bitbucket_create_branch requires a local clone. This tool creates
a branch in the locally cloned working tree (git checkout -b), not
directly on the remote. This matches the typical workflow where a
branch is immediately used for local modifications. To make the branch
visible on the remote, follow up with bitbucket_push_branch.

License

MIT. See LICENSE.

Related projects

• mcp-atlassian — MCP
  server for Jira and Confluence, supports both Cloud and Data Center,
  and includes OAuth 2.0 support for Data Center. Pairs well with this
  server if you want both Jira and Bitbucket tools.
• Model Context Protocol — the
  protocol this server implements.