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 seventeen 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

The typical end-to-end workflow uses the write tools in this order: clone → branch → write/edit/apply_patch → commit → push → PR.

Local file editing

The bitbucket_write_file, bitbucket_edit_file, and bitbucket_apply_patch tools operate on the locally cloned working tree in the configured workspace, not on the remote. This keeps the server's write surface contained to a sandboxed directory that the user can inspect at any time with git diff before committing.

Choose the tool that best fits the change:

• `bitbucket_write_file` creates a new file or replaces a file

entirely. Best for generated files or rewriting small files from scratch. Creates parent directories as needed.

• `bitbucket_edit_file` replaces a single unique occurrence of

an exact string with another. Fails loudly if the old string is not found or is found more than once. Best for surgical edits where the surrounding context is known and unambiguous.

• `bitbucket_apply_patch` applies a unified diff via git apply.

Best for multi-file coherent changes or when a diff is more compact than a sequence of individual edits.

All three tools validate paths against directory traversal, enforce the server's BITBUCKET_MAX_FILE_BYTES limit, and require the repo to already be cloned via bitbucket_clone_repo.

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. Write tools validate that target file paths stay inside the cloned repo directory.

• 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 and file-edit 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.

• Credential helper bypass. Every git invocation passes

-c credential.helper= to prevent the subprocess from consulting the user's credential manager, which can hang indefinitely in non-interactive environments.

• LFS filter bypass by default. See the LFS section below for

the full rationale and how to opt in.

• 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.

LFS handling

Git LFS support is controlled by BITBUCKET_LFS_MODE:

• `disabled` (default): every git invocation bypasses LFS filters

via -c filter.lfs.required=false -c filter.lfs.smudge=cat -c filter.lfs.clean=cat -c filter.lfs.process=. Repositories that use git-lfs will have their LFS-tracked files materialized as pointer files rather than real content. This is safe across any environment because it does not depend on git-lfs being installed.

• `enabled`: LFS filters are left alone. Requires git-lfs to be

reachable from the subprocess PATH. If git-lfs is missing and the user's .gitconfig declares filter.lfs.required = true, git will hang indefinitely during checkout. Use only when you control the subprocess environment.

• `auto`: at startup, the server checks for git-lfs in the

subprocess PATH. If found, LFS is enabled; otherwise it is disabled. Good middle ground for mixed environments where LFS may or may not be installed.

The default is disabled because silent deadlocks are much worse than pointer files in a working tree: pointer files are immediately visible on inspection, deadlocks look like the server is hung.

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",
        "BITBUCKET_LFS_MODE": "disabled"
      }
    }
  }
}

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.

Windows notes

On Windows, some MCP clients (notably Claude Desktop from the Microsoft Store) spawn the server subprocess with a sanitized environment that does not inherit the user's full PATH. If git.exe is installed in a non-standard location, for example inside a portable cmder distribution at C:\cmder\vendor\git-for-windows\cmd\, the subprocess will not find it and all git operations will fail.

To fix this, add an explicit PATH entry to the server's env block in your client configuration. Example for Git for Windows installed at its default location:

"env": {
  "PATH": "C:\\Program Files\\Git\\cmd;C:\\Program Files\\Git\\bin;C:\\Windows\\System32;C:\\Windows",
  "BITBUCKET_BASE_URL": "..."
}

For a cmder-bundled Git for Windows, the PATH typically needs to include cmd, bin, usr\bin, and (if you want LFS) mingw64\bin subdirectories of the cmder git installation.

This server handles the Windows-specific subprocess quirks of Git for Windows internally: stdout and stderr are routed through temporary files rather than anonymous pipes, working around a hang that can occur during git's early process initialization when its standard handles are Python-created pipes. No user configuration is required for this workaround.

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, apply these code changes, commit them, push the branch, 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 over 100 tests covering configuration loading, input validation, logging and secret redaction, git runner subprocess handling, HTTP client SSRF protection, the write-side tools (write_file, edit_file, apply_patch), and the read-side tools via HTTP client mocks. 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.

Single token, read and write. The server currently uses one BITBUCKET_TOKEN for all operations. There is no separation between a read-only token for exploration and a read-write token for committing and pushing. If you need to restrict what AI assistants can do, scope the single token at the Bitbucket side accordingly; a future version may add separate tokens for read and write operations.

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.

LFS disabled by default. Repositories that use git-lfs will see their LFS-tracked files as pointer files rather than real content unless BITBUCKET_LFS_MODE=enabled is set and git-lfs is reachable in the subprocess PATH. See the LFS section under Configuration.

Client-side timeouts on long operations. Some MCP clients (including early versions of Claude Desktop) enforce a client-side timeout on tool invocations. Cloning or pulling very large repositories may hit this timeout. The server mitigates this by sending notifications/progress messages every 10 seconds during long git operations, which resets the client's inactivity counter. If your client does not honor progress notifications and you hit timeouts, pre-clone the repository once outside the server so that subsequent calls go through the faster fetch + pull path.

Alpha status. APIs, tool names, and argument shapes may change before the first stable release. Do not depend on them from production code.

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.