{"id":50607021,"url":"https://github.com/diomonogatari/stash-mcp","last_synced_at":"2026-06-06T00:03:04.028Z","repository":{"id":337524289,"uuid":"1153004109","full_name":"diomonogatari/stash-mcp","owner":"diomonogatari","description":"MCP Server to connect with your Bitbucket Server (aka Stash)","archived":false,"fork":false,"pushed_at":"2026-06-05T13:19:09.000Z","size":256,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-06-05T14:14:07.469Z","etag":null,"topics":["bitbucket","mcp-server","mcp-servers","modelcontextprotocol"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/diomonogatari.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-08T18:55:10.000Z","updated_at":"2026-06-05T12:41:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/diomonogatari/stash-mcp","commit_stats":null,"previous_names":["diomonogatari/stash-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/diomonogatari/stash-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diomonogatari%2Fstash-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diomonogatari%2Fstash-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diomonogatari%2Fstash-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diomonogatari%2Fstash-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/diomonogatari","download_url":"https://codeload.github.com/diomonogatari/stash-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diomonogatari%2Fstash-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33964367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitbucket","mcp-server","mcp-servers","modelcontextprotocol"],"created_at":"2026-06-06T00:03:03.547Z","updated_at":"2026-06-06T00:03:04.021Z","avatar_url":"https://github.com/diomonogatari.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stash MCP Server\r\n\r\n[![CI](https://github.com/diomonogatari/stash-mcp/actions/workflows/build.yml/badge.svg)](https://github.com/diomonogatari/stash-mcp/actions/workflows/build.yml)\r\n[![codecov](https://codecov.io/gh/diomonogatari/stash-mcp/graph/badge.svg)](https://codecov.io/gh/diomonogatari/stash-mcp)\r\n[![Docker Pulls](https://img.shields.io/docker/pulls/diomonogatari/stash-mcp)](https://hub.docker.com/r/diomonogatari/stash-mcp)\r\n[![Docker Image Size](https://img.shields.io/docker/image-size/diomonogatari/stash-mcp/latest)](https://hub.docker.com/r/diomonogatari/stash-mcp)\r\n[![GitHub Release](https://img.shields.io/github/v/release/diomonogatari/stash-mcp)](https://github.com/diomonogatari/stash-mcp/releases)\r\n[![license](https://img.shields.io/github/license/diomonogatari/stash-mcp)](https://github.com/diomonogatari/stash-mcp/blob/main/LICENSE)\r\n![.NET 10.0](https://img.shields.io/badge/.net-10.0-512BD4)\r\n\r\nA Model Context Protocol (MCP) server for Atlassian Bitbucket Server (Stash), distributed as a Docker image on [Docker Hub](https://hub.docker.com/r/diomonogatari/stash-mcp). It gives AI assistants access to your repositories, pull requests, code reviews, builds, and search — through 41 purpose-built tools.\r\n\r\n## Features\r\n\r\n**41 tools** covering comprehensive Bitbucket Server workflows:\r\n\r\n| Category | Tools | Highlights |\r\n|----------|-------|-----------|\r\n| **Projects** | 1 | Discover projects |\r\n| **Dashboard** | 5 | User-centric PR views + server info |\r\n| **Repositories** | 3 | Repos, overview, file content |\r\n| **Git** | 3 | Branches, tags, file listing |\r\n| **Search** | 4 | Code, commits, PRs, users |\r\n| **History** | 5 | List/inspect commits, compare refs, full commit context |\r\n| **Pull Requests** | 8 | List/get/context/diff + create/update/merge + approve |\r\n| **Comments** | 4 | Read, write, reply with code context |\r\n| **Tasks** | 4 | Full CRUD for review tasks |\r\n| **Builds** | 3 | CI/CD status per commit/PR/repo |\r\n| **Integrations** | 1 | Jira issue links |\r\n\r\n### Workflow-Optimized Tools\r\n\r\nThese tools reduce multiple API calls to a single invocation:\r\n\r\n- `get_pull_request_context` — Complete PR with comments, tasks, diff, activity\r\n- `get_repository_overview` — Branches, tags, and open PRs in one call\r\n- `get_commit_context` — Commit details with changes and diff\r\n\r\n### Resilience\r\n\r\n- **Circuit Breaker** — Prevents cascading failures when Bitbucket is unavailable\r\n- **Retry with Backoff** — Automatic retry for transient errors (429, 502, 503, 504)\r\n- **Graceful Degradation** — Returns cached data when the API fails\r\n- **Response Truncation** — 50 KB limit prevents context overflow\r\n- **Cache Invalidation** — Write operations automatically refresh related caches\r\n\r\n## Getting Started\r\n\r\n### Prerequisites\r\n\r\n- [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed\r\n- A Bitbucket Server (self-hosted) instance\r\n- A Personal Access Token with repository read/write permissions\r\n\r\n### VS Code / Copilot — MCP Configuration\r\n\r\nAdd the following to your VS Code MCP configuration file\r\n(Command Palette → `MCP: Open user configuration`):\r\n\r\n```json\r\n{\r\n  \"servers\": {\r\n    \"stash-bitbucket\": {\r\n      \"command\": \"docker\",\r\n      \"args\": [\r\n        \"run\", \"-i\", \"--rm\",\r\n        \"-e\", \"BITBUCKET_URL\",\r\n        \"-e\", \"BITBUCKET_TOKEN\",\r\n        \"diomonogatari/stash-mcp:latest\"\r\n      ],\r\n      \"env\": {\r\n        \"BITBUCKET_URL\": \"https://your-stash-server.com/\",\r\n        \"BITBUCKET_TOKEN\": \"your_personal_access_token\"\r\n      },\r\n      \"type\": \"stdio\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nThat's it. VS Code will pull the image on first use and start the server automatically.\r\n\r\n\u003e **Tip — pin to a specific tag** instead of `latest` (e.g. `diomonogatari/stash-mcp:1.1.0`)\r\n\u003e to avoid running a stale local image when a new version is published.\r\n\u003e Docker skips the pull when a local image already has the `latest` tag.\r\n\u003e If you must use `latest`, force a pull with\r\n\u003e `docker run --pull=always ... diomonogatari/stash-mcp:latest`.\r\n\r\n### Use with Claude Desktop\r\n\r\nOpen **Settings → Developer → Edit Config** (or edit `claude_desktop_config.json`\r\ndirectly) and add the server under the `mcpServers` key:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"stash-bitbucket\": {\r\n      \"command\": \"docker\",\r\n      \"args\": [\r\n        \"run\", \"-i\", \"--rm\",\r\n        \"-e\", \"BITBUCKET_URL\",\r\n        \"-e\", \"BITBUCKET_TOKEN\",\r\n        \"diomonogatari/stash-mcp:latest\"\r\n      ],\r\n      \"env\": {\r\n        \"BITBUCKET_URL\": \"https://your-stash-server.com/\",\r\n        \"BITBUCKET_TOKEN\": \"your_personal_access_token\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nConfig file location:\r\n\r\n| OS | Path |\r\n|----|------|\r\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\r\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\r\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\r\n\r\nQuit and relaunch Claude Desktop after saving. The Bitbucket tools appear under\r\nthe tools (slider) icon. Docker Desktop must be running.\r\n\r\n\u003e **Note:** Claude Desktop uses the `mcpServers` key (and no `\"type\"` field),\r\n\u003e whereas the VS Code example above uses the `servers` key. The `command` and\r\n\u003e `args` are identical.\r\n\r\n### Use with Claude Code\r\n\r\n```bash\r\nclaude mcp add stash-bitbucket \\\r\n  --transport stdio \\\r\n  --env BITBUCKET_URL=https://your-stash-server.com/ \\\r\n  --env BITBUCKET_TOKEN=your_personal_access_token \\\r\n  -- docker run -i --rm -e BITBUCKET_URL -e BITBUCKET_TOKEN diomonogatari/stash-mcp:latest\r\n```\r\n\r\nThis registers the server at **local** scope (current project, just you). Use\r\n`--scope user` to make it available across all your projects, or `--scope project`\r\nto commit it to a shared `.mcp.json`. Verify with `claude mcp list` or the `/mcp`\r\ncommand inside a session (it should report `stash-bitbucket` connected with 41\r\ntools), and remove it with `claude mcp remove stash-bitbucket`.\r\n\r\n### Advanced Configuration\r\n\r\nPass additional environment variables to tune resilience and caching behaviour:\r\n\r\n```json\r\n{\r\n  \"servers\": {\r\n    \"stash-bitbucket\": {\r\n      \"command\": \"docker\",\r\n      \"args\": [\r\n        \"run\", \"-i\", \"--rm\",\r\n        \"-e\", \"BITBUCKET_URL\",\r\n        \"-e\", \"BITBUCKET_TOKEN\",\r\n        \"-e\", \"BITBUCKET_RETRY_COUNT\",\r\n        \"-e\", \"BITBUCKET_CIRCUIT_TIMEOUT\",\r\n        \"-e\", \"BITBUCKET_CACHE_TTL_SECONDS\",\r\n        \"-e\", \"BITBUCKET_READ_ONLY_MODE\",\r\n        \"-e\", \"BITBUCKET_PROJECTS\",\r\n        \"diomonogatari/stash-mcp:latest\"\r\n      ],\r\n      \"env\": {\r\n        \"BITBUCKET_URL\": \"https://your-stash-server.com/\",\r\n        \"BITBUCKET_TOKEN\": \"your_personal_access_token\",\r\n        \"BITBUCKET_RETRY_COUNT\": \"5\",\r\n        \"BITBUCKET_CIRCUIT_TIMEOUT\": \"60\",\r\n        \"BITBUCKET_CACHE_TTL_SECONDS\": \"120\",\r\n        \"BITBUCKET_READ_ONLY_MODE\": \"false\",\r\n        \"BITBUCKET_PROJECTS\": \"PROJ,TEAM\"\r\n      },\r\n      \"type\": \"stdio\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Configuration Reference\r\n\r\n| Setting | Environment Variable | Default | Description |\r\n|---------|---------------------|---------|-------------|\r\n| Server URL | `BITBUCKET_URL` | — | Bitbucket Server base URL (**required**) |\r\n| Access Token | `BITBUCKET_TOKEN` | — | Personal Access Token (**required**) |\r\n| Retry Count | `BITBUCKET_RETRY_COUNT` | 3 | Max retry attempts (0–10) |\r\n| Circuit Timeout | `BITBUCKET_CIRCUIT_TIMEOUT` | 30 | Circuit breaker duration in seconds (5–300) |\r\n| Cache TTL | `BITBUCKET_CACHE_TTL_SECONDS` | 60 | Cache time-to-live in seconds (10–600) |\r\n| Read-Only Mode | `BITBUCKET_READ_ONLY_MODE` | false | Disable write operations (`true` or `1`) |\r\n| Projects | `BITBUCKET_PROJECTS` | — | Comma-separated project keys to cache at startup (e.g. `PROJ,TEAM`). When omitted, derives scope from recent repositories. |\r\n\r\n## Tool Reference\r\n\r\nFor detailed documentation of all 41 tools, see [docs/TOOLSET.md](docs/TOOLSET.md).\r\n\r\n### Common Workflows\r\n\r\n#### Code Review\r\n\r\n```text\r\n1. get_pull_request_context (with includeComments=true, includeDiff=true)\r\n2. Review the diff and existing comments\r\n3. add_pull_request_comment (for feedback)\r\n4. create_pull_request_task (for required changes)\r\n5. approve_pull_request (when satisfied)\r\n```\r\n\r\n#### Bug Investigation\r\n\r\n```text\r\n1. search_commits (messageContains=\"JIRA-123\")\r\n2. get_commit_context (includeDiff=true)\r\n3. search_code (to find current implementation)\r\n```\r\n\r\n#### Repository Exploration\r\n\r\n```text\r\n1. get_repository_overview (quick overview)\r\n2. list_files (browse structure)\r\n3. get_file_content (read specific files)\r\n```\r\n\r\n### Output Optimization\r\n\r\nFor list operations, use `minimalOutput=true` to reduce response size:\r\n\r\n- `list_repositories` — Returns repository slugs only\r\n- `list_branches` — Returns branch names only\r\n- `list_pull_requests` — Returns compact PR summary\r\n\r\n## Contributing\r\n\r\n### Setup\r\n\r\n1. Clone the repository **with submodules**:\r\n\r\n   ```bash\r\n   git clone --recurse-submodules https://github.com/diomonogatari/stash-mcp.git\r\n   ```\r\n\r\n   If you already cloned without submodules:\r\n\r\n   ```bash\r\n   git submodule update --init --recursive\r\n   ```\r\n\r\n2. Install the [.NET 10.0 SDK](https://dotnet.microsoft.com/download)\r\n\r\n### Building\r\n\r\n```bash\r\n# Build the solution\r\ndotnet build stash-mcp.slnx\r\n\r\n# Run tests\r\ndotnet test stash-mcp.slnx\r\n```\r\n\r\n### Running Locally\r\n\r\n```bash\r\ndotnet run --project src/StashMcpServer/StashMcpServer.csproj -- \\\r\n  --stash-url https://your-server.com/ --pat your_pat\r\n```\r\n\r\n\u003e The double dash (`--`) separates `dotnet run` arguments from application arguments.\r\n\r\n#### CLI Flags\r\n\r\n| Flag | Default | Description |\r\n|------|---------|-------------|\r\n| `--stash-url` | `BITBUCKET_URL` env var | Bitbucket Server base URL |\r\n| `--pat` | `BITBUCKET_TOKEN` env var | Personal Access Token |\r\n| `--log-level` | `Information` | Serilog log level: `Verbose`, `Debug`, `Information`, `Warning`, `Error`, `Fatal` |\r\n\r\n### Building the Docker Image\r\n\r\n```bash\r\ndocker build -t diomonogatari/stash-mcp:dev .\r\ndocker run -i --rm \\\r\n  -e BITBUCKET_URL=https://your-stash-server.com/ \\\r\n  -e BITBUCKET_TOKEN=your_personal_access_token \\\r\n  diomonogatari/stash-mcp:dev\r\n```\r\n\r\n## Troubleshooting\r\n\r\n### Docker image not updating\r\n\r\nDocker skips the pull when the `latest` tag already exists locally.\r\nForce a fresh pull:\r\n\r\n```bash\r\ndocker pull diomonogatari/stash-mcp:latest\r\n```\r\n\r\nOr pin to a specific version tag (e.g. `diomonogatari/stash-mcp:1.1.0`).\r\n\r\n### Connection refused / timeout\r\n\r\n- Verify `BITBUCKET_URL` includes the trailing slash and protocol\r\n  (`https://your-server.com/`)\r\n- Ensure the Docker container can reach your Bitbucket Server (check\r\n  corporate VPN, proxy, or firewall rules)\r\n- For Docker Desktop on macOS/Windows, use `host.docker.internal` if\r\n  Bitbucket runs on the host machine\r\n\r\n### Permission errors (401 / 403)\r\n\r\n- Verify the Personal Access Token has **Repository Read** (and\r\n  **Repository Write** if you need write operations) permissions\r\n- Check that the token has not expired\r\n- Set `BITBUCKET_READ_ONLY_MODE=true` if only read access is needed\r\n\r\n### Server unresponsive after startup\r\n\r\n- Increase the log level to see what is happening:\r\n  `--log-level Debug` (CLI) or append `--log-level Debug` after the image\r\n  name in the `docker run` command\r\n- Check that the `BITBUCKET_PROJECTS` variable (if set) contains\r\n  valid project keys — invalid keys cause the startup cache to fail\r\n  silently\r\n\r\n## Architecture\r\n\r\n```text\r\n┌──────────────────────────────────────────────────────────┐\r\n│                      MCP Server Layer                    │\r\n│  ┌──────────────────────────────────────────────────┐    │\r\n│  │ Domain Tool Classes (9 classes, 41 tools)        │    │\r\n│  │  ProjectTools  RepositoryTools  PullRequestTools │    │\r\n│  │  SearchTools   GitTools   HistoryTools           │    │\r\n│  │  BuildTools    DashboardTools  IntegrationTools  │    │\r\n│  └──────────┬───────────────────────────────────────┘    │\r\n│             │ inherits ToolBase (shared helpers)         │\r\n│  ┌──────────▼───────────────────────────────────────┐    │\r\n│  │ Formatting  │ DiffFormatter  ResponseTruncation  │    │\r\n│  │             │ MinimalOutputFormatter (50KB limit)│    │\r\n│  └──────────┬───────────────────────────────────────┘    │\r\n│             │                                            │\r\n│  ┌──────────▼───────────────────────────────────────┐    │\r\n│  │           ResilientApiService                    │    │\r\n│  │  • Circuit Breaker (Polly)                       │    │\r\n│  │  • Retry with Exponential Backoff                │    │\r\n│  │  • Graceful Degradation (stale cache)            │    │\r\n│  │  • Cache Invalidation on Writes                  │    │\r\n│  └──────────┬───────────────────────────────────────┘    │\r\n│             │                                            │\r\n│  ┌──────────▼──────┐ ┌──────────────────────────────┐    │\r\n│  │ Cache Layer      │ │ IMemoryCache (TTL=60s)      │    │\r\n│  │ (Static)         │ │ ConcurrentDict (projects)   │    │\r\n│  └──────────┬──────┘ └──────────────────────────────┘    │\r\n│             │                                            │\r\n│  Transport: stdio                                        │\r\n└─────────────┼────────────────────────────────────────────┘\r\n              │\r\n              ▼\r\n       Bitbucket Server API (via Bitbucket.Net submodule)\r\n```\r\n\r\nFor detailed architecture documentation, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).\r\n\r\n## Security\r\n\r\n**Never commit your Personal Access Token to source control.**\r\n\r\n- Use environment variables (as shown in the configuration examples above)\r\n- Restrict PAT permissions to the minimum required scopes\r\n- Use secure credential storage where available\r\n\r\n## Documentation\r\n\r\n- [Architecture](docs/ARCHITECTURE.md) — System design and folder structure\r\n- [Tool Reference](docs/TOOLSET.md) — Detailed documentation for all 41 tools\r\n- [Contributing](CONTRIBUTING.md) — Development setup and pull request guidelines\r\n- [Security](SECURITY.md) — Vulnerability reporting and credential safety\r\n- [Changelog](CHANGELOG.md) — Version history and release notes\r\n\r\n## Star History\r\n\r\n\u003cpicture\u003e\r\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=diomonogatari/stash-mcp\u0026type=Date\u0026theme=dark\" /\u003e\r\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=diomonogatari/stash-mcp\u0026type=Date\" /\u003e\r\n  \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=diomonogatari/stash-mcp\u0026type=Date\" /\u003e\r\n\u003c/picture\u003e\r\n\r\n## License\r\n\r\nSee [LICENSE](LICENSE) for details.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiomonogatari%2Fstash-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdiomonogatari%2Fstash-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiomonogatari%2Fstash-mcp/lists"}