nicolas/bitbucket-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Update README and CLAUDE files

Browse Source
This commit is contained in:
Nicolas FRADIN
2026-05-19 17:12:56 +02:00
parent e89d33686c
commit c6080b4b98
2 changed files with 47 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
CLAUDE.md
View File

@@ -25,7 +25,7 @@ The server is a 3-layer pipeline: **MCP protocol** -> **Router** -> **Bitbucket
- `src/index.ts` — MCP server setup. Registers tool schemas (inputSchema definitions) and delegates `CallToolRequest` to the router. This is where new tools must be declared. - `src/index.ts` — MCP server setup. Registers tool schemas (inputSchema definitions) and delegates `CallToolRequest` to the router. This is where new tools must be declared.
- `src/router.ts` — `BitbucketRouter` maps tool names to client methods. Handles parameter extraction (supports both `pullRequestId` and `pr_id` forms) and wraps results in `ToolResult { success, data?, error? }`. - `src/router.ts` — `BitbucketRouter` maps tool names to client methods. Handles parameter extraction (supports both `pullRequestId` and `pr_id` forms) and wraps results in `ToolResult { success, data?, error? }`.
- `src/bitbucket-client.ts` — Axios-based HTTP client against `api.bitbucket.org/2.0`. Uses Basic Auth (email + app password). Has async initialization with a polling `ensureInitialized()` guard on every public method. - `src/bitbucket-client.ts` — Axios-based HTTP client against `api.bitbucket.org/2.0`. Uses Basic Auth (email + API token). Has async initialization with a polling `ensureInitialized()` guard on every public method.
- `src/config.ts` — Credential loading with priority: env vars (`BITBUCKET_MCP_EMAIL`, `BITBUCKET_MCP_TOKEN`) > `.env` file > interactive prompt. Also loads `DEFAULT_WORKSPACE` and `DEFAULT_REPO` for optional parameter defaults. - `src/config.ts` — Credential loading with priority: env vars (`BITBUCKET_MCP_EMAIL`, `BITBUCKET_MCP_TOKEN`) > `.env` file > interactive prompt. Also loads `DEFAULT_WORKSPACE` and `DEFAULT_REPO` for optional parameter defaults.
## Adding a New Tool ## Adding a New Tool
@@ -40,7 +40,7 @@ The server is a 3-layer pipeline: **MCP protocol** -> **Router** -> **Bitbucket
| Variable | Purpose | | Variable | Purpose |
|----------|---------| |----------|---------|
| `BITBUCKET_MCP_EMAIL` | Bitbucket account email (Basic Auth username) | | `BITBUCKET_MCP_EMAIL` | Bitbucket account email (Basic Auth username) |
| `BITBUCKET_MCP_TOKEN` | Bitbucket app password (Basic Auth password) | | `BITBUCKET_MCP_TOKEN` | Bitbucket API token (Basic Auth password) |
| `DEFAULT_WORKSPACE` | Optional default workspace slug | | `DEFAULT_WORKSPACE` | Optional default workspace slug |
| `DEFAULT_REPO` | Optional default repository slug | | `DEFAULT_REPO` | Optional default repository slug |

98
README.md
View File

@@ -31,71 +31,37 @@ This MCP server exposes **read-only** Bitbucket Cloud Pull Request operations as
## Quick Start ## Quick Start
### Prerequisites Get up and running in 4 steps:
### 1. Prerequisites
- Node.js **24.13+** (see `.nvmrc`) - Node.js **24.13+** (see `.nvmrc`)
- A Bitbucket Cloud [API Token](https://id.atlassian.com/manage-profile/security/api-tokens) with **repository read** permissions - A Bitbucket Cloud [API Token](https://id.atlassian.com/manage-profile/security/api-tokens) with **repository read** permissions (note: App Passwords are no longer supported by Bitbucket)
### Installation ### 2. Install & Build
```bash ```bash
git clone <repository-url> git clone <repository-url>
cd bitbucket-mcp cd bitbucket-mcp
npm install npm install
```
### Configuration
Create a `.env` file in the project root:
```env
BITBUCKET_MCP_EMAIL=your_email@example.com
BITBUCKET_MCP_TOKEN=your_app_password
# Optional defaults (avoids passing workspace/repo on every call)
DEFAULT_WORKSPACE=my-workspace
DEFAULT_REPO=my-repo
```
Or export as environment variables (takes priority over `.env`):
```bash
export BITBUCKET_MCP_EMAIL=your_email@example.com
export BITBUCKET_MCP_TOKEN=your_app_password
```
### Run
```bash
# Production
npm start
# Development (hot reload)
npm run dev
# Build
npm run build npm run build
``` ```
--- ### 3. Configure in Claude
## MCP Client Configuration Add the MCP server to your Claude configuration:
### Claude Code **Claude Code** — edit `~/.claude/settings.json` (global) or `.claude/settings.json` (per-project):
Add the following to your Claude Code MCP settings (`~/.claude/settings.json` or project `.claude/settings.json`):
```json ```json
{ {
"mcpServers": { "mcpServers": {
"bitbucket": { "bitbucket": {
"command": "node", "command": "node",
"args": [ "args": ["/absolute/path/to/bitbucket-mcp/dist/index.js"],
"/absolute/path/to/bitbucket-mcp/dist/index.js"
],
"env": { "env": {
"BITBUCKET_MCP_EMAIL": "your_email@example.com", "BITBUCKET_MCP_EMAIL": "your_email@example.com",
"BITBUCKET_MCP_TOKEN": "your_bitbucket_app_password", "BITBUCKET_MCP_TOKEN": "your_api_token",
"DEFAULT_WORKSPACE": "your-workspace", "DEFAULT_WORKSPACE": "your-workspace",
"DEFAULT_REPO": "your-repo" "DEFAULT_REPO": "your-repo"
} }
@@ -104,21 +70,17 @@ Add the following to your Claude Code MCP settings (`~/.claude/settings.json` or
} }
``` ```
### Claude Desktop **Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
```json ```json
{ {
"mcpServers": { "mcpServers": {
"bitbucket": { "bitbucket": {
"command": "node", "command": "node",
"args": [ "args": ["/absolute/path/to/bitbucket-mcp/dist/index.js"],
"/absolute/path/to/bitbucket-mcp/dist/index.js"
],
"env": { "env": {
"BITBUCKET_MCP_EMAIL": "your_email@example.com", "BITBUCKET_MCP_EMAIL": "your_email@example.com",
"BITBUCKET_MCP_TOKEN": "your_bitbucket_app_password", "BITBUCKET_MCP_TOKEN": "your_api_token",
"DEFAULT_WORKSPACE": "your-workspace", "DEFAULT_WORKSPACE": "your-workspace",
"DEFAULT_REPO": "your-repo" "DEFAULT_REPO": "your-repo"
} }
@@ -127,7 +89,14 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
} }
``` ```
> **Note:** You must build the project first (`npm run build`) since the config points to `dist/index.js`. Use the **absolute path** to the compiled entry point. Setting `DEFAULT_WORKSPACE` and `DEFAULT_REPO` is optional but convenient — it lets you omit those parameters from every tool call. > **Important:**
> - Replace `/absolute/path/to/bitbucket-mcp` with the actual absolute path where you cloned the repo.
> - `DEFAULT_WORKSPACE` and `DEFAULT_REPO` are optional but convenient — they let you omit those parameters from every tool call.
> - Get your API token from [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
### 4. Verify
Restart Claude (or reload MCP servers), then ask Claude to run the `validate_token` tool. If credentials are correct, it will confirm the connection is working.
--- ---
@@ -213,6 +182,27 @@ Response:
## Development ## Development
### Running Locally
For development, you can use a `.env` file instead of configuring credentials in the MCP client:
```env
BITBUCKET_MCP_EMAIL=your_email@example.com
BITBUCKET_MCP_TOKEN=your_api_token
DEFAULT_WORKSPACE=my-workspace
DEFAULT_REPO=my-repo
```
```bash
# Run with hot reload
npm run dev
# Or run directly
npm start
```
### Testing
```bash ```bash
# Run tests # Run tests
npm test npm test
@@ -250,7 +240,9 @@ tests/
This server uses **HTTP Basic Authentication** with the Bitbucket Cloud REST API v2.0: This server uses **HTTP Basic Authentication** with the Bitbucket Cloud REST API v2.0:
- **Username** = your Bitbucket email - **Username** = your Bitbucket email
- **Password** = an [App Password](https://bitbucket.org/account/settings/app-passwords/) - **Password** = an [API Token](https://id.atlassian.com/manage-profile/security/api-tokens)
> **Note:** Bitbucket no longer supports App Passwords. You must use an API Token instead.
Credential resolution order: Credential resolution order:
1. Environment variables (`BITBUCKET_MCP_EMAIL` + `BITBUCKET_MCP_TOKEN`) 1. Environment variables (`BITBUCKET_MCP_EMAIL` + `BITBUCKET_MCP_TOKEN`)