stash

This MCP server, stash-mcp, runs as a Docker image and exposes a suite of tools that provide AI-powered interactions with a Bitbucket Server (Stash) instance. It offers around 40 purpose-built tools that cover common Bitbucket workflows, including repository discovery, PR guidance, code search, commit history, file content access, and build/status checks. The server is designed to minimize API calls by providing workflow-optimized tools (for example, get_pull_request_context, get_repository_overview, and get_commit_context) and includes resilience features such as a circuit breaker, retry logic, and cached responses to keep experiences smooth even when the Bitbucket API is slow or temporarily unavailable. To use it, run the Docker image with your Bitbucket server URL and a personal access token, and connect via your MCP-enabled editor or tooling that supports the MCP protocol.

Prerequisites:

• Docker Desktop installed on your development machine or server
• Bitbucket Server (Stash) instance reachable from the machine running the MCP server
• A Personal Access Token (PAT) with repository read/write permissions on the Bitbucket server

Installation steps:

1. Ensure Docker is running and you have network access to your Bitbucket Server.
2. Pull and run the MCP Docker image with required environment variables:

# Basic run with required environment variables
docker run -i --rm \
  -e BITBUCKET_URL=https://your-stash-server.com/ \
  -e BITBUCKET_TOKEN=your_personal_access_token \
  diomonogatari/stash-mcp:latest

3. If you want to pin a specific tag to avoid automatic updates, replace latest with a version tag, e.g. 1.1.0:

docker run -i --rm \
  -e BITBUCKET_URL=https://your-stash-server.com/ \
  -e BITBUCKET_TOKEN=your_personal_access_token \
  diomonogatari/stash-mcp:1.1.0

4. Connect your MCP-enabled editor (e.g., VS Code) using the provided configuration example in the README, ensuring the environment variables match your Bitbucket deployment.

• Required environment variables: BITBUCKET_URL (Bitbucket Server base URL) and BITBUCKET_TOKEN (PAT) must be provided for the MCP to authenticate with Bitbucket.
• You can tune resilience and caching with additional environment variables such as BITBUCKET_RETRY_COUNT, BITBUCKET_CIRCUIT_TIMEOUT, BITBUCKET_CACHE_TTL_SECONDS, BITBUCKET_READ_ONLY_MODE, and BITBUCKET_PROJECTS to pre-cache certain projects.
• When upgrading, consider pinning to a specific tag to avoid unexpected breaks from latest tag changes.
• If running behind a corporate proxy, ensure Docker is configured to access external resources and that the Bitbucket URL is reachable from the container.
• The MCP server exposes a large set of tools; for best results, consult the docs/TOOLSET.md in the repository for detailed capabilities and usage patterns.