mokkenstorm.dev
cli / mcp for bitbucket
1# bitbucket-tool-mcp
2
3MCP server for [Bitbucket Cloud](https://bitbucket.org). Gives AI assistants (Claude, Cursor, etc.) direct access to pull requests, pipelines, branches, commits, and code review workflows.
4
5## Tools
6
7| Tool | Description |
8|------|-------------|
9| `list_repositories` | List repositories in a workspace |
10| `list_branches` | List branches in a repository |
11| `get_branch` | Get branch details and latest commit |
12| `create_branch` | Create a branch from a commit or branch |
13| `delete_branch` | Delete a branch |
14| `list_pull_requests` | List PRs, filterable by state |
15| `get_pull_request` | Get PR details (title, branches, author, status) |
16| `create_pull_request` | Create a new PR |
17| `update_pull_request` | Update PR title, description, or destination |
18| `decline_pull_request` | Decline (close) a PR |
19| `get_pull_request_diff` | Get raw unified diff for a PR |
20| `get_pull_request_comments` | Get all comments including inline code review |
21| `add_pull_request_comment` | Add a comment to a PR |
22| `list_pipelines` | List recent pipeline runs |
23| `get_pipeline` | Get pipeline details and steps |
24| `get_pipeline_step_log` | Get raw log output for a pipeline step |
25| `trigger_pipeline` | Trigger a pipeline on a branch or tag |
26| `list_commits` | List recent commits |
27| `get_commit` | Get commit details |
28
29## Installation
30
31### Claude Desktop / Claude Code
32
33Add to your MCP config (`~/.claude.json` or Claude Desktop settings):
34
35```json
36{
37 "mcpServers": {
38 "bitbucket": {
39 "command": "npx",
40 "args": ["-y", "bitbucket-tool-mcp"],
41 "env": {
42 "BITBUCKET_TOKEN": "your-api-token",
43 "BITBUCKET_WORKSPACE": "your-workspace"
44 }
45 }
46 }
47}
48```
49
50### Cursor
51
52Add to `.cursor/mcp.json` in your project root:
53
54```json
55{
56 "mcpServers": {
57 "bitbucket": {
58 "command": "npx",
59 "args": ["-y", "bitbucket-tool-mcp"],
60 "env": {
61 "BITBUCKET_TOKEN": "your-api-token",
62 "BITBUCKET_WORKSPACE": "your-workspace"
63 }
64 }
65 }
66}
67```
68
69### Other MCP clients
70
71Any MCP client that supports stdio transport works. Run the server directly:
72
73```bash
74BITBUCKET_TOKEN=your-token npx bitbucket-tool-mcp
75```
76
77## Authentication
78
79### API Token (recommended)
80
81Set `BITBUCKET_TOKEN` to a [Bitbucket API token](https://bitbucket.org/account/settings/app-passwords/) or [workspace access token](https://bitbucket.org/account/settings/). The token needs read/write access to repositories, pull requests, and pipelines depending on which tools you use.
82
83```bash
84export BITBUCKET_TOKEN="your-api-token"
85```
86
87### OAuth 2.0
88
89For OAuth flows, set both client ID and secret. Create an OAuth consumer in your Bitbucket workspace settings under **OAuth consumers**.
90
91```bash
92export BITBUCKET_OAUTH_CLIENT_ID="your-client-id"
93export BITBUCKET_OAUTH_CLIENT_SECRET="your-client-secret"
94```
95
96## Configuration
97
98| Environment variable | Required | Description |
99|---------------------|----------|-------------|
100| `BITBUCKET_TOKEN` | Yes* | API token for Bearer auth |
101| `BITBUCKET_OAUTH_CLIENT_ID` | Yes* | OAuth 2.0 client ID |
102| `BITBUCKET_OAUTH_CLIENT_SECRET` | Yes* | OAuth 2.0 client secret |
103| `BITBUCKET_WORKSPACE` | No | Default workspace (can also be passed per tool call) |
104
105*One auth method required: either `BITBUCKET_TOKEN` or both OAuth variables.
106
107## Local Development
108
109```bash
110git clone https://github.com/riotbyte-com/bitbucket-tool.git
111cd bitbucket-tool
112npm install
113npm run build
114
115# Run tests
116npm test
117
118# Run with MCP Inspector for interactive testing
119npx @modelcontextprotocol/inspector node packages/mcp-server/dist/index.js
120```
121
122## License
123
124MIT