mokkenstorm.dev
cli / mcp for bitbucket
1# bitbucket-tool
2
3Type-safe Bitbucket Cloud tooling: an MCP server for AI assistants and a CLI for humans.
4
5## Packages
6
7| Package | Description | npm |
8|---------|-------------|-----|
9| [`bitbucket-tool-mcp`](./packages/mcp-server) | MCP server (19 tools for PRs, pipelines, branches, commits) | `npx bitbucket-tool-mcp` |
10| [`bitbucket-tool-cli`](./packages/cli) | CLI for common Bitbucket operations | `npx bitbucket-tool-cli` |
11| `@bitbucket-tool/core` | Shared API client and service layer (internal) | -- |
12
13## Quick Start
14
15### MCP Server
16
17Add to your Claude Desktop / Claude Code config:
18
19```json
20{
21 "mcpServers": {
22 "bitbucket": {
23 "command": "npx",
24 "args": ["-y", "bitbucket-tool-mcp"],
25 "env": {
26 "BITBUCKET_TOKEN": "your-api-token",
27 "BITBUCKET_WORKSPACE": "your-workspace"
28 }
29 }
30 }
31}
32```
33
34See [MCP server README](./packages/mcp-server/README.md) for full documentation.
35
36### CLI
37
38```bash
39npx bitbucket-tool-cli pr:list --workspace my-ws --repo my-repo
40```
41
42## Development
43
44```bash
45npm install
46npm run build
47npm test
48
49# Run MCP server locally
50npm run dev:mcp
51
52# Run CLI locally
53npm run dev:cli -- pr:list --workspace my-ws --repo my-repo
54
55# Interactive MCP testing
56npx @modelcontextprotocol/inspector node packages/mcp-server/dist/index.js
57
58# Lint / typecheck
59npm run lint
60npm run typecheck
61```
62
63## Project Structure
64
65```
66bitbucket-tool/
67├── packages/
68│ ├── core/ # Shared API client, services, auth, types
69│ ├── cli/ # CLI (Commander)
70│ └── mcp-server/ # MCP server (19 tools)
71└── scripts/
72 └── patch-spec.ts # OpenAPI spec patching for codegen
73```
74
75## Authentication
76
77Set one of:
78
79- **API token**: `BITBUCKET_TOKEN` env var
80- **OAuth 2.0**: `BITBUCKET_OAUTH_CLIENT_ID` + `BITBUCKET_OAUTH_CLIENT_SECRET`
81
82Optionally set `BITBUCKET_WORKSPACE` as a default workspace.
83
84## License
85
86MIT