Stash MCP
MCP Server to connect with your Bitbucket Server (aka Stash)
Ask AI about Stash MCP
Powered by Claude Β· Grounded in docs
I know everything about Stash MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Stash MCP Server
A Model Context Protocol (MCP) server for Atlassian Bitbucket Server (Stash), distributed as a Docker image on Docker Hub. It gives AI assistants access to your repositories, pull requests, code reviews, builds, and search β through 40 purpose-built tools.
Features
40 tools covering comprehensive Bitbucket Server workflows:
| Category | Tools | Highlights |
|---|---|---|
| Projects | 1 | Discover projects |
| Dashboard | 5 | User-centric PR views + server info |
| Repositories | 3 | Repos, overview, file content |
| Git | 3 | Branches, tags, file listing |
| Search | 4 | Code, commits, PRs, users |
| History | 5 | List/inspect commits, compare refs, full commit context |
| Pull Requests | 7 | List/get/context/diff + create/update + approve |
| Comments | 4 | Read, write, reply with code context |
| Tasks | 4 | Full CRUD for review tasks |
| Builds | 3 | CI/CD status per commit/PR/repo |
| Integrations | 1 | Jira issue links |
Workflow-Optimized Tools
These tools reduce multiple API calls to a single invocation:
get_pull_request_contextβ Complete PR with comments, tasks, diff, activityget_repository_overviewβ Branches, tags, and open PRs in one callget_commit_contextβ Commit details with changes and diff
Resilience
- Circuit Breaker β Prevents cascading failures when Bitbucket is unavailable
- Retry with Backoff β Automatic retry for transient errors (429, 502, 503, 504)
- Graceful Degradation β Returns cached data when the API fails
- Response Truncation β 50 KB limit prevents context overflow
- Cache Invalidation β Write operations automatically refresh related caches
Getting Started
Prerequisites
- Docker Desktop installed
- A Bitbucket Server (self-hosted) instance
- A Personal Access Token with repository read/write permissions
VS Code / Copilot β MCP Configuration
Add the following to your VS Code MCP configuration file
(Command Palette β MCP: Open user configuration):
{
"servers": {
"stash-bitbucket": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "BITBUCKET_URL",
"-e", "BITBUCKET_TOKEN",
"diomonogatari/stash-mcp:latest"
],
"env": {
"BITBUCKET_URL": "https://your-stash-server.com/",
"BITBUCKET_TOKEN": "your_personal_access_token"
},
"type": "stdio"
}
}
}
That's it. VS Code will pull the image on first use and start the server automatically.
Tip β pin to a specific tag instead of
latest(e.g.diomonogatari/stash-mcp:1.1.0) to avoid running a stale local image when a new version is published. Docker skips the pull when a local image already has thelatesttag. If you must uselatest, force a pull withdocker run --pull=always ... diomonogatari/stash-mcp:latest.
Advanced Configuration
Pass additional environment variables to tune resilience and caching behaviour:
{
"servers": {
"stash-bitbucket": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "BITBUCKET_URL",
"-e", "BITBUCKET_TOKEN",
"-e", "BITBUCKET_RETRY_COUNT",
"-e", "BITBUCKET_CIRCUIT_TIMEOUT",
"-e", "BITBUCKET_CACHE_TTL_SECONDS",
"-e", "BITBUCKET_READ_ONLY_MODE",
"-e", "BITBUCKET_PROJECTS",
"diomonogatari/stash-mcp:latest"
],
"env": {
"BITBUCKET_URL": "https://your-stash-server.com/",
"BITBUCKET_TOKEN": "your_personal_access_token",
"BITBUCKET_RETRY_COUNT": "5",
"BITBUCKET_CIRCUIT_TIMEOUT": "60",
"BITBUCKET_CACHE_TTL_SECONDS": "120",
"BITBUCKET_READ_ONLY_MODE": "false",
"BITBUCKET_PROJECTS": "PROJ,TEAM"
},
"type": "stdio"
}
}
}
Configuration Reference
| Setting | Environment Variable | Default | Description |
|---|---|---|---|
| Server URL | BITBUCKET_URL | β | Bitbucket Server base URL (required) |
| Access Token | BITBUCKET_TOKEN | β | Personal Access Token (required) |
| Retry Count | BITBUCKET_RETRY_COUNT | 3 | Max retry attempts (0β10) |
| Circuit Timeout | BITBUCKET_CIRCUIT_TIMEOUT | 30 | Circuit breaker duration in seconds (5β300) |
| Cache TTL | BITBUCKET_CACHE_TTL_SECONDS | 60 | Cache time-to-live in seconds (10β600) |
| Read-Only Mode | BITBUCKET_READ_ONLY_MODE | false | Disable write operations (true or 1) |
| Projects | BITBUCKET_PROJECTS | β | Comma-separated project keys to cache at startup (e.g. PROJ,TEAM). When omitted, derives scope from recent repositories. |
Tool Reference
For detailed documentation of all 40 tools, see docs/TOOLSET.md.
Common Workflows
Code Review
1. get_pull_request_context (with includeComments=true, includeDiff=true)
2. Review the diff and existing comments
3. add_pull_request_comment (for feedback)
4. create_pull_request_task (for required changes)
5. approve_pull_request (when satisfied)
Bug Investigation
1. search_commits (messageContains="JIRA-123")
2. get_commit_context (includeDiff=true)
3. search_code (to find current implementation)
Repository Exploration
1. get_repository_overview (quick overview)
2. list_files (browse structure)
3. get_file_content (read specific files)
Output Optimization
For list operations, use minimalOutput=true to reduce response size:
list_repositoriesβ Returns repository slugs onlylist_branchesβ Returns branch names onlylist_pull_requestsβ Returns compact PR summary
Contributing
Setup
-
Clone the repository with submodules:
git clone --recurse-submodules https://github.com/diomonogatari/stash-mcp.gitIf you already cloned without submodules:
git submodule update --init --recursive -
Install the .NET 10.0 SDK
Building
# Build the solution
dotnet build stash-mcp.slnx
# Run tests
dotnet test stash-mcp.slnx
Running Locally
dotnet run --project src/StashMcpServer/StashMcpServer.csproj -- \
--stash-url https://your-server.com/ --pat your_pat
The double dash (
--) separatesdotnet runarguments from application arguments.
CLI Flags
| Flag | Default | Description |
|---|---|---|
--stash-url | BITBUCKET_URL env var | Bitbucket Server base URL |
--pat | BITBUCKET_TOKEN env var | Personal Access Token |
--log-level | Information | Serilog log level: Verbose, Debug, Information, Warning, Error, Fatal |
Building the Docker Image
docker build -t diomonogatari/stash-mcp:dev .
docker run -i --rm \
-e BITBUCKET_URL=https://your-stash-server.com/ \
-e BITBUCKET_TOKEN=your_personal_access_token \
diomonogatari/stash-mcp:dev
Troubleshooting
Docker image not updating
Docker skips the pull when the latest tag already exists locally.
Force a fresh pull:
docker pull diomonogatari/stash-mcp:latest
Or pin to a specific version tag (e.g. diomonogatari/stash-mcp:1.1.0).
Connection refused / timeout
- Verify
BITBUCKET_URLincludes the trailing slash and protocol (https://your-server.com/) - Ensure the Docker container can reach your Bitbucket Server (check corporate VPN, proxy, or firewall rules)
- For Docker Desktop on macOS/Windows, use
host.docker.internalif Bitbucket runs on the host machine
Permission errors (401 / 403)
- Verify the Personal Access Token has Repository Read (and Repository Write if you need write operations) permissions
- Check that the token has not expired
- Set
BITBUCKET_READ_ONLY_MODE=trueif only read access is needed
Server unresponsive after startup
- Increase the log level to see what is happening:
--log-level Debug(CLI) or append--log-level Debugafter the image name in thedocker runcommand - Check that the
BITBUCKET_PROJECTSvariable (if set) contains valid project keys β invalid keys cause the startup cache to fail silently
Architecture
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MCP Server Layer β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Domain Tool Classes (9 classes, 40 tools) β β
β β ProjectTools RepositoryTools PullRequestTools β β
β β SearchTools GitTools HistoryTools β β
β β BuildTools DashboardTools IntegrationTools β β
β ββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββ β
β β inherits ToolBase (shared helpers) β
β ββββββββββββΌββββββββββββββββββββββββββββββββββββββββ β
β β Formatting β DiffFormatter ResponseTruncation β β
β β β MinimalOutputFormatter (50KB limit)β β
β ββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββ β
β β β
β ββββββββββββΌββββββββββββββββββββββββββββββββββββββββ β
β β ResilientApiService β β
β β β’ Circuit Breaker (Polly) β β
β β β’ Retry with Exponential Backoff β β
β β β’ Graceful Degradation (stale cache) β β
β β β’ Cache Invalidation on Writes β β
β ββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββ β
β β β
β ββββββββββββΌβββββββ ββββββββββββββββββββββββββββββββ β
β β Cache Layer β β IMemoryCache (TTL=60s) β β
β β (Static) β β ConcurrentDict (projects) β β
β ββββββββββββ¬βββββββ ββββββββββββββββββββββββββββββββ β
β β β
β Transport: stdio β
βββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
Bitbucket Server API (via Bitbucket.Net submodule)
For detailed architecture documentation, see docs/ARCHITECTURE.md.
Security
Never commit your Personal Access Token to source control.
- Use environment variables (as shown in the configuration examples above)
- Restrict PAT permissions to the minimum required scopes
- Use secure credential storage where available
Documentation
- Architecture β System design and folder structure
- Tool Reference β Detailed documentation for all 40 tools
- Contributing β Development setup and pull request guidelines
- Security β Vulnerability reporting and credential safety
- Changelog β Version history and release notes
Star History
License
See LICENSE for details.
