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

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