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 resi

... View full README on GitHub