Update README and CLAUDE files
This commit is contained in:
98
README.md
98
README.md
@@ -31,71 +31,37 @@ This MCP server exposes **read-only** Bitbucket Cloud Pull Request operations as
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
Get up and running in 4 steps:
|
||||
|
||||
### 1. Prerequisites
|
||||
|
||||
- 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
|
||||
git clone <repository-url>
|
||||
cd bitbucket-mcp
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
### 3. Configure in Claude
|
||||
|
||||
## MCP Client Configuration
|
||||
Add the MCP server to your Claude configuration:
|
||||
|
||||
### Claude Code
|
||||
|
||||
Add the following to your Claude Code MCP settings (`~/.claude/settings.json` or project `.claude/settings.json`):
|
||||
**Claude Code** — edit `~/.claude/settings.json` (global) or `.claude/settings.json` (per-project):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"bitbucket": {
|
||||
"command": "node",
|
||||
"args": [
|
||||
"/absolute/path/to/bitbucket-mcp/dist/index.js"
|
||||
],
|
||||
"args": ["/absolute/path/to/bitbucket-mcp/dist/index.js"],
|
||||
"env": {
|
||||
"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_REPO": "your-repo"
|
||||
}
|
||||
@@ -104,21 +70,17 @@ Add the following to your Claude Code MCP settings (`~/.claude/settings.json` or
|
||||
}
|
||||
```
|
||||
|
||||
### Claude Desktop
|
||||
|
||||
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):
|
||||
**Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"bitbucket": {
|
||||
"command": "node",
|
||||
"args": [
|
||||
"/absolute/path/to/bitbucket-mcp/dist/index.js"
|
||||
],
|
||||
"args": ["/absolute/path/to/bitbucket-mcp/dist/index.js"],
|
||||
"env": {
|
||||
"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_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
|
||||
|
||||
### 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
|
||||
# Run tests
|
||||
npm test
|
||||
@@ -250,7 +240,9 @@ tests/
|
||||
This server uses **HTTP Basic Authentication** with the Bitbucket Cloud REST API v2.0:
|
||||
|
||||
- **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:
|
||||
1. Environment variables (`BITBUCKET_MCP_EMAIL` + `BITBUCKET_MCP_TOKEN`)
|
||||
|
||||
Reference in New Issue
Block a user