stash-mcp

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 41 purpose-built tools.

Features

41 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	8	List/get/context/diff + create/update/merge + 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, activity
• get_repository_overview — Branches, tags, and open PRs in one call
• get_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 the latest tag. If you must use latest, force a pull with docker run --pull=always ... diomonogatari/stash-mcp:latest.

Use with Claude Desktop

Open Settings → Developer → Edit Config (or edit claude_desktop_config.json directly) and add the server under the mcpServers key:

{
  "mcpServers": {
    "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"
      }
    }
  }
}

Config file location:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Quit and relaunch Claude Desktop after saving. The Bitbucket tools appear under the tools (slider) icon. Docker Desktop must be running.

Note: Claude Desktop uses the mcpServers key (and no "type" field), whereas the VS Code example above uses the servers key. The command and args are identical.

Use with Claude Code

claude mcp add stash-bitbucket \
  --transport stdio \
  --env BITBUCKET_URL=https://your-stash-server.com/ \
  --env BITBUCKET_TOKEN=your_personal_access_token \
  -- docker run -i --rm -e BITBUCKET_URL -e BITBUCKET_TOKEN diomonogatari/stash-mcp:latest

This registers the server at local scope (current project, just you). Use --scope user to make it available across all your projects, or --scope project to commit it to a shared .mcp.json. Verify with claude mcp list or the /mcp command inside a session (it should report stash-bitbucket connected with 41 tools), and remove it with claude mcp remove stash-bitbucket.

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 41 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 only
• list_branches — Returns branch names only
• list_pull_requests — Returns compact PR summary

Contributing

Setup

1. Clone the repository with submodules:

   git clone --recurse-submodules https://github.com/diomonogatari/stash-mcp.git
   

   If you already cloned without submodules:

   git submodule update --init --recursive
   

2. 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 (--) separates dotnet run arguments 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_URL includes 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.internal if 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=true if 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 Debug after the image name in the docker run command
• Check that the BITBUCKET_PROJECTS variable (if set) contains valid project keys — invalid keys cause the startup cache to fail silently

Architecture

┌──────────────────────────────────────────────────────────┐
│                      MCP Server Layer                    │
│  ┌──────────────────────────────────────────────────┐    │
│  │ Domain Tool Classes (9 classes, 41 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 41 tools
• Local Bitbucket — Run a real Bitbucket Server in Docker for end-to-end testing
• 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.