mcp-server-bitbucket 0.8.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. mcp_server_bitbucket-0.8.1/.claude/settings.local.json +49 -0
  2. mcp_server_bitbucket-0.8.1/.env.example +7 -0
  3. mcp_server_bitbucket-0.8.1/.gitignore +19 -0
  4. mcp_server_bitbucket-0.8.1/CLAUDE.md +151 -0
  5. mcp_server_bitbucket-0.8.1/Dockerfile +28 -0
  6. mcp_server_bitbucket-0.8.1/PKG-INFO +396 -0
  7. mcp_server_bitbucket-0.8.1/README.md +372 -0
  8. mcp_server_bitbucket-0.8.1/docs/INSTALLATION.md +427 -0
  9. mcp_server_bitbucket-0.8.1/docs/ROADMAP.md +213 -0
  10. mcp_server_bitbucket-0.8.1/pyproject.toml +50 -0
  11. mcp_server_bitbucket-0.8.1/scripts/measure_token_savings.py +335 -0
  12. mcp_server_bitbucket-0.8.1/src/__init__.py +1 -0
  13. mcp_server_bitbucket-0.8.1/src/bitbucket_client.py +1513 -0
  14. mcp_server_bitbucket-0.8.1/src/formatter.py +122 -0
  15. mcp_server_bitbucket-0.8.1/src/http_server.py +228 -0
  16. mcp_server_bitbucket-0.8.1/src/models.py +661 -0
  17. mcp_server_bitbucket-0.8.1/src/server.py +1561 -0
  18. mcp_server_bitbucket-0.8.1/src/settings.py +107 -0
  19. mcp_server_bitbucket-0.8.1/src/tools/__init__.py +1 -0
  20. mcp_server_bitbucket-0.8.1/src/utils.py +143 -0
  21. mcp_server_bitbucket-0.8.1/tests/__init__.py +1 -0
  22. mcp_server_bitbucket-0.8.1/tests/conftest.py +104 -0
  23. mcp_server_bitbucket-0.8.1/tests/test_bitbucket_client.py +359 -0
  24. mcp_server_bitbucket-0.8.1/tests/test_formatter.py +265 -0
  25. mcp_server_bitbucket-0.8.1/tests/test_models.py +644 -0
  26. mcp_server_bitbucket-0.8.1/tests/test_server.py +96 -0
  27. mcp_server_bitbucket-0.8.1/tests/test_utils.py +203 -0
  28. mcp_server_bitbucket-0.8.1/uv.lock +1214 -0
mcp_server_bitbucket-0.8.1/.claude/settings.local.json ADDED
@@ -0,0 +1,49 @@
1
+ {
2
+ "permissions": {
3
+ "allow": [
4
+ "Bash(echo:*)",
5
+ "Bash(claude mcp list:*)",
6
+ "WebSearch",
7
+ "WebFetch(domain:developer.atlassian.com)",
8
+ "Bash(python -c:*)",
9
+ "Bash(python:*)",
10
+ "mcp__bitbucket__list_repositories",
11
+ "Bash(poetry build:*)",
12
+ "Bash(poetry publish:*)",
13
+ "Bash(pipx upgrade:*)",
14
+ "Bash(pipx uninstall:*)",
15
+ "Bash(pipx install:*)",
16
+ "Bash(git add:*)",
17
+ "mcp__bitbucket__get_commit_statuses",
18
+ "mcp__bitbucket__compare_commits",
19
+ "mcp__bitbucket__list_pr_comments",
20
+ "Bash(poetry run python:*)",
21
+ "Bash(poetry install:*)",
22
+ "Bash(poetry lock:*)",
23
+ "Bash(poetry run pytest:*)",
24
+ "mcp__bitbucket__list_projects",
25
+ "mcp__bitbucket__list_branches",
26
+ "mcp__bitbucket__list_commits",
27
+ "mcp__bitbucket__list_tags",
28
+ "mcp__bitbucket__get_repository",
29
+ "Bash(pip show:*)",
30
+ "Bash(pip install:*)",
31
+ "Bash(python3:*)",
32
+ "Bash(uv run:*)",
33
+ "Bash(cat:*)",
34
+ "Bash(security find-generic-password:*)",
35
+ "Bash(uv sync:*)",
36
+ "Bash(poetry config pypi-token.pypi)",
37
+ "Bash(poetry config:*)",
38
+ "Bash(tree:*)",
39
+ "Bash(find:*)",
40
+ "Bash(uv publish:*)",
41
+ "Bash(git push:*)",
42
+ "Bash(uv build:*)"
43
+ ]
44
+ },
45
+ "enableAllProjectMcpServers": true,
46
+ "enabledMcpjsonServers": [
47
+ "bitbucket"
48
+ ]
49
+ }
mcp_server_bitbucket-0.8.1/.env.example ADDED
@@ -0,0 +1,7 @@
1
+ # Bitbucket API credentials
2
+ BITBUCKET_WORKSPACE=simplekyc
3
+ BITBUCKET_EMAIL=your-email@example.com
4
+ BITBUCKET_API_TOKEN=your-app-password
5
+
6
+ # Optional: Default project key for new repos
7
+ BITBUCKET_PROJECT_KEY=
mcp_server_bitbucket-0.8.1/.gitignore ADDED
@@ -0,0 +1,19 @@
1
+ # Environment
2
+ .env
3
+ .venv/
4
+ venv/
5
+ __pycache__/
6
+ *.pyc
7
+
8
+ # IDE
9
+ .idea/
10
+ .vscode/
11
+ *.swp
12
+
13
+ # Build
14
+ dist/
15
+ *.egg-info/
16
+ build/
17
+
18
+ # Poetry
19
+ poetry.lock
mcp_server_bitbucket-0.8.1/CLAUDE.md ADDED
@@ -0,0 +1,151 @@
1
+ # CLAUDE.md
2
+
3
+ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+ ## Project Overview
6
+
7
+ This is an MCP (Model Context Protocol) server for Bitbucket API operations. It provides tools for interacting with Bitbucket repositories, pull requests, pipelines, branches, commits, tags, deployments, webhooks, branch restrictions, source browsing, and permissions. The server works with Claude Code, Claude Desktop, and any MCP-compatible client.
8
+
9
+ ## Development Commands
10
+
11
+ ```bash
12
+ # Install dependencies
13
+ uv sync
14
+
15
+ # Run MCP server (stdio mode for Claude Desktop/Code)
16
+ uv run python -m src.server
17
+
18
+ # Run HTTP server (for Cloud Run deployment)
19
+ uv run uvicorn src.http_server:app --reload --port 8080
20
+
21
+ # Run tests
22
+ uv run pytest
23
+
24
+ # Build and publish to PyPI
25
+ uv build
26
+ uv publish
27
+
28
+ # Tag a release
29
+ git tag v0.x.x && git push origin v0.x.x
30
+ ```
31
+
32
+ ## Architecture
33
+
34
+ The codebase has a simple layered architecture:
35
+
36
+ - **`src/server.py`**: FastMCP server that defines all 53 MCP tools. Each tool is a decorated function (`@mcp.tool()`) that wraps BitbucketClient methods, transforming raw API responses into cleaner dicts for LLM consumption.
37
+
38
+ - **`src/bitbucket_client.py`**: Low-level HTTP client for Bitbucket API 2.0. Uses httpx with Basic Auth. Contains all the actual API calls organized by domain (repositories, PRs, pipelines, etc.). Exposes a singleton via `get_client()`.
39
+
40
+ - **`src/settings.py`**: Centralized configuration using pydantic-settings. Loads environment variables and `.env` files. Provides `get_settings()` for cached access to configuration.
41
+
42
+ - **`src/formatter.py`**: Output formatter supporting JSON (default) and TOON formats. The `@formatted` decorator is applied to all tools to enable configurable output.
43
+
44
+ - **`src/models.py`**: Pydantic models for response transformation. Handles field renaming, timestamp truncation, and token optimization.
45
+
46
+ - **`src/http_server.py`**: FastAPI wrapper that exposes MCP tools as REST endpoints for Cloud Run deployment. Maps tool names to functions and provides convenience routes.
47
+
48
+ ## Configuration
49
+
50
+ The server requires three environment variables:
51
+ - `BITBUCKET_WORKSPACE`: Bitbucket workspace slug
52
+ - `BITBUCKET_EMAIL`: Account email for Basic Auth
53
+ - `BITBUCKET_API_TOKEN`: Repository access token
54
+
55
+ ### Output Format (Optional)
56
+
57
+ Set `OUTPUT_FORMAT` to control response format:
58
+ - `json` (default): Standard JSON responses, maximum compatibility
59
+ - `toon`: TOON format (Token-Oriented Object Notation) for ~30-40% token savings
60
+
61
+ ```bash
62
+ # Via environment variable
63
+ claude mcp add bitbucket -s user \
64
+ -e OUTPUT_FORMAT=toon \
65
+ -e BITBUCKET_WORKSPACE=... \
66
+ ...
67
+
68
+ # Or set in your shell
69
+ export OUTPUT_FORMAT=toon
70
+ ```
71
+
72
+ TOON is ideal for high-volume usage where token costs matter. JSON is recommended for debugging or when compatibility is important.
73
+
74
+ ## Adding New Tools
75
+
76
+ 1. Add the API method to `BitbucketClient` in `src/bitbucket_client.py`
77
+ 2. Create the MCP tool wrapper in `src/server.py` using `@mcp.tool()` decorator
78
+ 3. If exposing via HTTP, add to the `TOOLS` dict in `src/http_server.py`
79
+
80
+ ## Development Workflow
81
+
82
+ ### 1. Local Testing (Direct)
83
+
84
+ Test tools directly without Claude Code by importing and calling them:
85
+
86
+ ```python
87
+ # Test a tool directly
88
+ uv run python -c "
89
+ from src.server import list_repositories
90
+ print(list_repositories(limit=5))
91
+ "
92
+
93
+ # Or test the client layer
94
+ uv run python -c "
95
+ from src.bitbucket_client import get_client
96
+ client = get_client()
97
+ print(client.list_repositories(limit=5))
98
+ "
99
+ ```
100
+
101
+ ### 2. Local Testing with Claude Code
102
+
103
+ Configure Claude Code to use the local development version instead of the PyPI package:
104
+
105
+ ```bash
106
+ # Remove the PyPI version if installed
107
+ claude mcp remove bitbucket
108
+
109
+ # Add the local development version
110
+ claude mcp add bitbucket -s user \
111
+ -e BITBUCKET_WORKSPACE=your-workspace \
112
+ -e BITBUCKET_EMAIL=your-email@example.com \
113
+ -e BITBUCKET_API_TOKEN=your-token \
114
+ -- uv run --directory /path/to/bitbucket-mcp python -m src.server
115
+ ```
116
+
117
+ This allows testing changes immediately without publishing.
118
+
119
+ ### 3. Publishing to PyPI
120
+
121
+ ```bash
122
+ # 1. Bump version in pyproject.toml
123
+
124
+ # 2. Build the package
125
+ uv build
126
+
127
+ # 3. Publish to PyPI (set UV_PUBLISH_TOKEN env var or use --token)
128
+ uv publish
129
+
130
+ # 4. Tag the release
131
+ git tag v0.x.x
132
+ git push origin v0.x.x
133
+ ```
134
+
135
+ ### 4. Verify Published Version
136
+
137
+ ```bash
138
+ # Upgrade to the new version
139
+ pipx upgrade mcp-server-bitbucket
140
+
141
+ # If upgrade doesn't pick up the new version, reinstall:
142
+ pipx uninstall mcp-server-bitbucket
143
+ pipx install mcp-server-bitbucket
144
+
145
+ # Restart Claude Code session to pick up changes
146
+ # Then verify the tools are accessible
147
+ ```
148
+
149
+ ## Package Distribution
150
+
151
+ Published to PyPI as `mcp-server-bitbucket`. Users install via `pipx install mcp-server-bitbucket`. The entry point `mcp-server-bitbucket` runs `src.server:main`.
mcp_server_bitbucket-0.8.1/Dockerfile ADDED
@@ -0,0 +1,28 @@
1
+ FROM python:3.11-slim
2
+
3
+ WORKDIR /app
4
+
5
+ # Install uv
6
+ COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
7
+
8
+ # Copy dependency files and README
9
+ COPY pyproject.toml uv.lock README.md ./
10
+
11
+ # Install dependencies (without dev dependencies)
12
+ RUN uv sync --frozen --no-dev --no-install-project
13
+
14
+ # Copy source code
15
+ COPY src/ ./src/
16
+
17
+ # Install the project
18
+ RUN uv sync --frozen --no-dev
19
+
20
+ # Set environment variables
21
+ ENV PORT=8080
22
+ ENV PYTHONUNBUFFERED=1
23
+
24
+ # Expose port
25
+ EXPOSE 8080
26
+
27
+ # Run HTTP server
28
+ CMD ["uv", "run", "uvicorn", "src.http_server:app", "--host", "0.0.0.0", "--port", "8080"]
mcp_server_bitbucket-0.8.1/PKG-INFO ADDED
@@ -0,0 +1,396 @@
1
+ Metadata-Version: 2.4
2
+ Name: mcp-server-bitbucket
3
+ Version: 0.8.1
4
+ Summary: MCP server for Bitbucket API operations
5
+ Project-URL: Homepage, https://bitbucket.org/simplekyc/bitbucket-mcp
6
+ Project-URL: Documentation, https://bitbucket.org/simplekyc/bitbucket-mcp/src/main/docs/INSTALLATION.md
7
+ Project-URL: Bug Tracker, https://bitbucket.org/simplekyc/bitbucket-mcp/issues
8
+ Author: Javier Aguilar
9
+ Keywords: ai,api,bitbucket,claude,mcp
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Requires-Python: >=3.11
16
+ Requires-Dist: fastapi>=0.115
17
+ Requires-Dist: httpx>=0.27
18
+ Requires-Dist: mcp>=1.23.1
19
+ Requires-Dist: pydantic-settings>=2.0
20
+ Requires-Dist: pydantic>=2.0
21
+ Requires-Dist: toon-llm>=1.0.0b6
22
+ Requires-Dist: uvicorn>=0.32
23
+ Description-Content-Type: text/markdown
24
+
25
+ # Bitbucket MCP Server
26
+
27
+ MCP server for Bitbucket API operations. Works with Claude Code, Claude Desktop, and any MCP-compatible client.
28
+
29
+ ## Features
30
+
31
+ - **Repositories**: get, create, delete, list, update (move to project, rename)
32
+ - **Pull Requests**: create, get, list, merge, approve, decline, request changes, comments, diff
33
+ - **Pipelines**: trigger, get status, list, view logs, stop
34
+ - **Branches**: list, get
35
+ - **Projects**: list, get
36
+ - **Commits**: list, get details, compare/diff between branches
37
+ - **Commit Statuses**: get build statuses, create status (CI/CD integration)
38
+ - **Deployments**: list environments, get environment details, deployment history
39
+ - **Webhooks**: list, create, get, delete
40
+ - **Tags**: list, create, delete
41
+ - **Branch Restrictions**: list, create, delete branch protection rules
42
+ - **Source Browsing**: read files, list directories without cloning
43
+ - **Repository Permissions**: manage user and group permissions
44
+
45
+ ## Quick Start
46
+
47
+ ```bash
48
+ # Install
49
+ pipx install mcp-server-bitbucket
50
+
51
+ # Configure Claude Code
52
+ claude mcp add bitbucket -s user \
53
+ -e BITBUCKET_WORKSPACE=your-workspace \
54
+ -e BITBUCKET_EMAIL=your-email@example.com \
55
+ -e BITBUCKET_API_TOKEN=your-api-token \
56
+ -- mcp-server-bitbucket
57
+ ```
58
+
59
+ **[Full Installation Guide](https://bitbucket.org/simplekyc/bitbucket-mcp/src/main/docs/INSTALLATION.md)** - Includes API token creation, permissions setup, and troubleshooting.
60
+
61
+ ## Available Tools (53 total)
62
+
63
+ ### Repositories
64
+ | Tool | Description |
65
+ |------|-------------|
66
+ | `list_repositories` | List and search repositories (supports fuzzy name matching) |
67
+ | `get_repository` | Get repository details |
68
+ | `create_repository` | Create a new repository |
69
+ | `delete_repository` | Delete a repository |
70
+ | `update_repository` | Update repo settings (project, visibility, description, name) |
71
+
72
+ ### Branches & Commits
73
+ | Tool | Description |
74
+ |------|-------------|
75
+ | `list_branches` | List branches in a repo |
76
+ | `get_branch` | Get branch details |
77
+ | `list_commits` | List commits (filter by branch or file path) |
78
+ | `get_commit` | Get commit details |
79
+ | `compare_commits` | Compare two commits/branches (diff stats) |
80
+
81
+ ### Tags
82
+ | Tool | Description |
83
+ |------|-------------|
84
+ | `list_tags` | List tags in a repo |
85
+ | `create_tag` | Create a new tag |
86
+ | `delete_tag` | Delete a tag |
87
+
88
+ ### Branch Restrictions
89
+ | Tool | Description |
90
+ |------|-------------|
91
+ | `list_branch_restrictions` | List branch protection rules |
92
+ | `create_branch_restriction` | Create branch protection rule |
93
+ | `delete_branch_restriction` | Delete branch protection rule |
94
+
95
+ ### Source (File Browsing)
96
+ | Tool | Description |
97
+ |------|-------------|
98
+ | `get_file_content` | Read file contents without cloning |
99
+ | `list_directory` | List directory contents |
100
+
101
+ ### Commit Statuses (CI/CD)
102
+ | Tool | Description |
103
+ |------|-------------|
104
+ | `get_commit_statuses` | Get build/CI statuses for a commit |
105
+ | `create_commit_status` | Report build status from external CI |
106
+
107
+ ### Pull Requests
108
+ | Tool | Description |
109
+ |------|-------------|
110
+ | `list_pull_requests` | List PRs (open, merged, etc.) |
111
+ | `get_pull_request` | Get PR details |
112
+ | `create_pull_request` | Create a new PR |
113
+ | `merge_pull_request` | Merge a PR |
114
+ | `approve_pr` | Approve a PR |
115
+ | `unapprove_pr` | Remove approval from a PR |
116
+ | `request_changes_pr` | Request changes on a PR |
117
+ | `decline_pr` | Decline (close) a PR |
118
+ | `list_pr_comments` | List comments on a PR |
119
+ | `add_pr_comment` | Add comment to a PR (general or inline) |
120
+ | `get_pr_diff` | Get the diff of a PR |
121
+
122
+ ### Pipelines
123
+ | Tool | Description |
124
+ |------|-------------|
125
+ | `list_pipelines` | List recent pipeline runs |
126
+ | `get_pipeline` | Get pipeline status |
127
+ | `get_pipeline_logs` | View pipeline logs |
128
+ | `trigger_pipeline` | Trigger a pipeline run |
129
+ | `stop_pipeline` | Stop a running pipeline |
130
+
131
+ ### Deployments
132
+ | Tool | Description |
133
+ |------|-------------|
134
+ | `list_environments` | List deployment environments (test, staging, prod) |
135
+ | `get_environment` | Get environment details |
136
+ | `list_deployment_history` | Get deployment history for an environment |
137
+
138
+ ### Webhooks
139
+ | Tool | Description |
140
+ |------|-------------|
141
+ | `list_webhooks` | List configured webhooks |
142
+ | `create_webhook` | Create a new webhook |
143
+ | `get_webhook` | Get webhook details |
144
+ | `delete_webhook` | Delete a webhook |
145
+
146
+ ### Repository Permissions
147
+ | Tool | Description |
148
+ |------|-------------|
149
+ | `list_user_permissions` | List user permissions for a repo |
150
+ | `get_user_permission` | Get specific user's permission |
151
+ | `update_user_permission` | Add/update user permission |
152
+ | `delete_user_permission` | Remove user permission |
153
+ | `list_group_permissions` | List group permissions for a repo |
154
+ | `get_group_permission` | Get specific group's permission |
155
+ | `update_group_permission` | Add/update group permission |
156
+ | `delete_group_permission` | Remove group permission |
157
+
158
+ ### Projects
159
+ | Tool | Description |
160
+ |------|-------------|
161
+ | `list_projects` | List projects in workspace |
162
+ | `get_project` | Get project details |
163
+
164
+ ## Example Usage
165
+
166
+ Once configured, ask Claude to:
167
+
168
+ **Repositories & Branches:**
169
+ - "List all repositories in my workspace"
170
+ - "Search for repositories with 'api' in the name"
171
+ - "Show me the last 10 commits on the main branch"
172
+ - "Compare develop branch with main"
173
+
174
+ **Pull Requests & Code Review:**
175
+ - "Show me open pull requests in my-repo"
176
+ - "Create a PR from feature-branch to main"
177
+ - "Approve PR #42"
178
+ - "Add a comment to PR #15 saying 'Looks good!'"
179
+ - "Show me the diff for PR #42"
180
+ - "Merge PR #42 using squash strategy"
181
+
182
+ **Pipelines & CI/CD:**
183
+ - "Trigger a pipeline on the develop branch"
184
+ - "What's the status of the latest pipeline?"
185
+ - "Get the build status for commit abc123"
186
+
187
+ **Deployments:**
188
+ - "List deployment environments for my-repo"
189
+ - "Show deployment history for production"
190
+
191
+ **Webhooks:**
192
+ - "List webhooks configured for my-repo"
193
+ - "Create a webhook for push events"
194
+
195
+ **Tags:**
196
+ - "List all tags in my-repo"
197
+ - "Create a tag v1.0.0 on the main branch"
198
+ - "Delete the old-release tag"
199
+
200
+ **Branch Protection:**
201
+ - "List branch restrictions for my-repo"
202
+ - "Require 2 approvals to merge to main"
203
+ - "Prevent force push to production branches"
204
+
205
+ **Source Browsing:**
206
+ - "Show me the contents of src/main.py"
207
+ - "List files in the root directory"
208
+ - "Read the README.md from the develop branch"
209
+
210
+ **Repository Permissions:**
211
+ - "List user permissions for my-repo"
212
+ - "Give user@example.com write access to my-repo"
213
+ - "List group permissions for my-repo"
214
+ - "Grant admin access to the DevOps group"
215
+
216
+ ### Repository Search
217
+
218
+ The `list_repositories` tool supports flexible searching:
219
+
220
+ ```python
221
+ # Simple fuzzy search by name
222
+ list_repositories(search="api") # Finds repos with "api" in name
223
+
224
+ # Advanced Bitbucket query syntax
225
+ list_repositories(query='name ~ "test" AND is_private = true')
226
+
227
+ # Filter by project
228
+ list_repositories(project_key="MYPROJECT")
229
+ ```
230
+
231
+ Query syntax supports: `name ~ "term"`, `is_private = true/false`, `AND`, `OR`
232
+
233
+ ## Installation Options
234
+
235
+ ### From PyPI (Recommended)
236
+
237
+ ```bash
238
+ pipx install mcp-server-bitbucket
239
+ # or
240
+ pip install mcp-server-bitbucket
241
+ ```
242
+
243
+ ### Updating
244
+
245
+ ```bash
246
+ # Upgrade to latest version
247
+ pipx upgrade mcp-server-bitbucket
248
+
249
+ # If upgrade doesn't pick up the new version, reinstall:
250
+ pipx uninstall mcp-server-bitbucket
251
+ pipx install mcp-server-bitbucket
252
+ ```
253
+
254
+ ### From Source
255
+
256
+ ```bash
257
+ git clone git@bitbucket.org:simplekyc/bitbucket-mcp.git
258
+ cd bitbucket-mcp
259
+ uv sync
260
+ ```
261
+
262
+ ## Configuration
263
+
264
+ ### Claude Code CLI (Recommended)
265
+
266
+ ```bash
267
+ claude mcp add bitbucket -s user \
268
+ -e BITBUCKET_WORKSPACE=your-workspace \
269
+ -e BITBUCKET_EMAIL=your-email@example.com \
270
+ -e BITBUCKET_API_TOKEN=your-api-token \
271
+ -- mcp-server-bitbucket
272
+ ```
273
+
274
+ ### Output Format (Optional)
275
+
276
+ Set `OUTPUT_FORMAT` to optimize token usage:
277
+
278
+ ```bash
279
+ # TOON format for ~30-40% token savings
280
+ claude mcp add bitbucket -s user \
281
+ -e OUTPUT_FORMAT=toon \
282
+ -e BITBUCKET_WORKSPACE=your-workspace \
283
+ -e BITBUCKET_EMAIL=your-email@example.com \
284
+ -e BITBUCKET_API_TOKEN=your-api-token \
285
+ -- mcp-server-bitbucket
286
+ ```
287
+
288
+ | Format | Description | Use case |
289
+ |--------|-------------|----------|
290
+ | `json` (default) | Standard JSON | Maximum compatibility, debugging |
291
+ | `toon` | [TOON format](https://toonformat.dev/) | High-volume usage, token cost optimization |
292
+
293
+ ### Manual Configuration
294
+
295
+ Add to `~/.claude.json`:
296
+
297
+ ```json
298
+ {
299
+ "mcpServers": {
300
+ "bitbucket": {
301
+ "command": "mcp-server-bitbucket",
302
+ "env": {
303
+ "BITBUCKET_WORKSPACE": "your-workspace",
304
+ "BITBUCKET_EMAIL": "your-email@example.com",
305
+ "BITBUCKET_API_TOKEN": "your-api-token",
306
+ "OUTPUT_FORMAT": "json"
307
+ }
308
+ }
309
+ }
310
+ }
311
+ ```
312
+
313
+ ## Creating a Bitbucket API Token
314
+
315
+ 1. Go to your repository in Bitbucket
316
+ 2. Navigate to **Repository settings** > **Access tokens**
317
+ 3. Click **Create Repository Access Token**
318
+ 4. Select permissions:
319
+ - **Repository**: Read, Write, Admin, Delete
320
+ - **Pull requests**: Read, Write
321
+ - **Pipelines**: Read, Write
322
+ 5. Copy the token immediately
323
+
324
+ See the [full installation guide](https://bitbucket.org/simplekyc/bitbucket-mcp/src/main/docs/INSTALLATION.md) for detailed instructions.
325
+
326
+ ## HTTP Server (Cloud Run)
327
+
328
+ For deploying as an HTTP API:
329
+
330
+ ```bash
331
+ # Run locally
332
+ uv run uvicorn src.http_server:app --reload --port 8080
333
+
334
+ # Deploy to Cloud Run
335
+ gcloud run deploy bitbucket-mcp-service \
336
+ --source . \
337
+ --region australia-southeast1 \
338
+ --set-secrets "BITBUCKET_EMAIL=bitbucket-email:latest,BITBUCKET_API_TOKEN=bitbucket-token:latest"
339
+ ```
340
+
341
+ ## Development
342
+
343
+ ### Requirements
344
+
345
+ - Python 3.11+
346
+ - [uv](https://docs.astral.sh/uv/) for dependency management
347
+ - [PyPI account](https://pypi.org/account/register/) for publishing
348
+
349
+ ### Setup
350
+
351
+ ```bash
352
+ git clone git@bitbucket.org:simplekyc/bitbucket-mcp.git
353
+ cd bitbucket-mcp
354
+ uv sync
355
+ ```
356
+
357
+ ### Running Locally
358
+
359
+ ```bash
360
+ # MCP server (stdio mode)
361
+ uv run python -m src.server
362
+
363
+ # HTTP server
364
+ uv run uvicorn src.http_server:app --reload --port 8080
365
+ ```
366
+
367
+ ### Publishing to PyPI
368
+
369
+ 1. **Get a PyPI API Token**:
370
+ - Go to https://pypi.org/manage/account/token/
371
+ - Create a token with scope "Entire account" (first time) or project-specific
372
+ - Set environment variable: `export UV_PUBLISH_TOKEN=pypi-YOUR_TOKEN`
373
+
374
+ 2. **Bump version** in `pyproject.toml`
375
+
376
+ 3. **Build and publish**:
377
+ ```bash
378
+ uv build
379
+ uv publish
380
+ ```
381
+
382
+ 4. **Tag the release**:
383
+ ```bash
384
+ git tag v0.x.x
385
+ git push origin v0.x.x
386
+ ```
387
+
388
+ ## Links
389
+
390
+ - [PyPI Package](https://pypi.org/project/mcp-server-bitbucket/)
391
+ - [Installation Guide](https://bitbucket.org/simplekyc/bitbucket-mcp/src/main/docs/INSTALLATION.md)
392
+ - [Bitbucket Repository](https://bitbucket.org/simplekyc/bitbucket-mcp)
393
+
394
+ ## License
395
+
396
+ MIT