@lexmata/bitbucket-mcp


A Model Context Protocol (MCP) server for Bitbucket Cloud - 25+ tools for repositories, pull requests, branches, commits, issues, pipelines, and code search.

Features

- Full Bitbucket Cloud API Coverage: Access repositories, pull requests, branches, commits, issues, pipelines, and code search
- OAuth 2.0 Authentication: Secure authentication with automatic browser-based sign-in and token refresh
- App Password Support: Alternative authentication using Bitbucket App Passwords
- MCP Tools: 25+ tools for interacting with Bitbucket
- MCP Resources: Access repositories, pull requests, and files as resources
- TypeScript: Fully typed for reliability and developer experience

Installation

``bash


Using npm

npm install -g @lexmata/bitbucket-mcp

Using pnpm

pnpm add -g @lexmata/bitbucket-mcp

Using yarn

yarn global add @lexmata/bitbucket-mcp
`

Configuration

$3

OAuth provides the best experience with automatic browser-based authentication and token refresh.

#### Step 1: Create an OAuth Consumer

1. Go to your Bitbucket workspace: https://bitbucket.org/{workspace}/workspace/settings/oauth-consumers
2. Click "Add consumer"
3. Fill in:
- Name: MCP Server (or any name)
- Callback URL: http://localhost:9876/callback (required)
- Permissions: Select the following:
- Account: Read
- Repositories: Read, Write, Admin
- Pull requests: Read, Write
- Issues: Read, Write
- Pipelines: Read, Write
4. Click Save and note the Key (Client ID) and Secret (Client Secret)

#### Step 2: Run the OAuth Flow

Use the included helper script to authenticate:

`bash


From the project directory


node scripts/oauth-flow.js "YOUR_CLIENT_ID" "YOUR_CLIENT_SECRET"
`

This will:

1. Start a local callback server on port 9876
2. Open your browser to Bitbucket's authorization page
3. After you authorize, display the configuration to add to your MCP config

#### Step 3: Configure Your MCP Client

Add the output configuration to your MCP client config file.

$3

For personal use without OAuth setup:

1. Go to Bitbucket: Personal Settings → App passwords
2. Click Create app password
3. Give it a name and select permissions:
- Account: Read
- Repositories: Read, Write, Admin
- Pull requests: Read, Write
- Issues: Read, Write
- Pipelines: Read, Write
4. Copy the generated password

Configure with your Bitbucket username and the app password:

`json
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": ["@lexmata/bitbucket-mcp"],
"env": {
"BITBUCKET_USERNAME": "your-username",
"BITBUCKET_ACCESS_TOKEN": "your-app-password"
}
}
}
}
`

Usage with Cursor IDE

Add the following to your Cursor MCP configuration file:

Linux: ~/.cursor/mcp.json
macOS: ~/.cursor/mcp.json
Windows: %USERPROFILE%\.cursor\mcp.json

$3

`json
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": ["@lexmata/bitbucket-mcp"],
"env": {
"BITBUCKET_CLIENT_ID": "your-client-id",
"BITBUCKET_CLIENT_SECRET": "your-client-secret",
"BITBUCKET_ACCESS_TOKEN": "your-access-token",
"BITBUCKET_REFRESH_TOKEN": "your-refresh-token"
}
}
}
}
`

When tokens expire, the server will automatically refresh them using the refresh token. If refresh fails, a browser window will open for re-authentication.

$3

`json
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": ["@lexmata/bitbucket-mcp"],
"env": {
"BITBUCKET_USERNAME": "your-username",
"BITBUCKET_ACCESS_TOKEN": "your-app-password"
}
}
}
}
`

Usage with Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

`json
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": ["@lexmata/bitbucket-mcp"],
"env": {
"BITBUCKET_CLIENT_ID": "your-client-id",
"BITBUCKET_CLIENT_SECRET": "your-client-secret",
"BITBUCKET_ACCESS_TOKEN": "your-access-token",
"BITBUCKET_REFRESH_TOKEN": "your-refresh-token"
}
}
}
}
`

Or if installed globally:

`json
{
"mcpServers": {
"bitbucket": {
"command": "bitbucket-mcp",
"env": {
"BITBUCKET_USERNAME": "your-username",
"BITBUCKET_ACCESS_TOKEN": "your-app-password"
}
}
}
}
`

Environment Variables

| Variable | Description | Required |
| ------------------------- | ---------------------------------- | ---------------- |
| BITBUCKET_CLIENT_ID | OAuth consumer key | For OAuth |
| BITBUCKET_CLIENT_SECRET | OAuth consumer secret | For OAuth |
| BITBUCKET_ACCESS_TOKEN | OAuth access token or App password | Yes |
| BITBUCKET_REFRESH_TOKEN | OAuth refresh token | For OAuth |
| BITBUCKET_USERNAME | Bitbucket username | For App Password |

Token Management

$3

- Access tokens expire after 2 hours
- Refresh tokens are used to automatically obtain new access tokens
- Tokens are persisted to ~/.config/bitbucket-mcp/tokens.json
- If tokens expire and refresh fails, the browser will automatically open for re-authentication

$3

If you need to re-authenticate manually:

`bash
node scripts/oauth-flow.js "YOUR_CLIENT_ID" "YOUR_CLIENT_SECRET"
`

Or delete the token file to trigger re-authentication:

`bash
rm ~/.config/bitbucket-mcp/tokens.json
`

Available Tools

$3

| Tool | Description |
| ----------------------- | ------------------------------------ |
| list_repositories | List repositories in a workspace |
| get_repository | Get details of a specific repository |
| create_repository | Create a new repository |
| delete_repository | Delete a repository |
| list_repository_forks | List all forks of a repository |

$3

| Tool | Description |
| ---------------------- | ------------------------------------------ |
| list_pull_requests | List pull requests with optional filtering |
| get_pull_request | Get details of a specific pull request |
| create_pull_request | Create a new pull request |
| update_pull_request | Update a pull request |
| merge_pull_request | Merge a pull request |
| decline_pull_request | Decline a pull request |
| approve_pull_request | Approve a pull request |
| request_changes | Request changes on a pull request |
| list_pr_comments | List comments on a pull request |
| add_pr_comment | Add a comment to a pull request |
| get_pr_diff | Get the diff for a pull request |

$3

| Tool | Description |
| --------------- | -------------------------------- |
| list_branches | List branches in a repository |
| get_branch | Get details of a specific branch |
| create_branch | Create a new branch |
| delete_branch | Delete a branch |

$3

| Tool | Description |
| ----------------- | ------------------------------------ |
| list_commits | List commits with optional filtering |
| get_commit | Get details of a specific commit |
| get_commit_diff | Get the diff for a commit |

$3

| Tool | Description |
| -------------- | ------------------------------- |
| list_issues | List issues in a repository |
| get_issue | Get details of a specific issue |
| create_issue | Create a new issue |
| update_issue | Update an issue |
| delete_issue | Delete an issue |

$3

| Tool | Description |
| ------------------ | ----------------------------- |
| list_pipelines | List pipeline runs |
| get_pipeline | Get details of a pipeline run |
| trigger_pipeline | Trigger a new pipeline run |
| stop_pipeline | Stop a running pipeline |

$3

| Tool | Description |
| ------------- | ------------------------------- |
| search_code | Search code across repositories |

$3

| Tool | Description |
| ------------------ | ------------------------- |
| get_file_content | Get the content of a file |

Resources

The server provides the following resource types:

| Resource URI | Description |
| ------------------------------------------------- | ---------------------- |
| bitbucket://repository/{workspace}/{repo} | Repository information |
| bitbucket://pullrequest/{workspace}/{repo}/{id} | Pull request details |
| bitbucket://file/{workspace}/{repo}/{path} | File contents |

Examples

$3

`
Use the list_repositories tool with workspace "my-workspace"
`

$3

`
Use the create_pull_request tool with:
- workspace: "my-workspace"
- repo_slug: "my-repo"
- title: "Add new feature"
- source_branch: "feature/new-feature"
- destination_branch: "main"
- description: "This PR adds a new feature"
`

$3

`
Use the search_code tool with:
- workspace: "my-workspace"
- search_query: "function handleError"
`

$3

`
Use the trigger_pipeline tool with:
- workspace: "my-workspace"
- repo_slug: "my-repo"
- ref_type: "branch"
- ref_name: "main"
`

Development

$3

- Node.js 18+
- pnpm 9+

$3

`bash


Clone the repository

git clone https://github.com/lexmata/bitbucket-mcp.git
cd bitbucket-mcp

Install dependencies

pnpm install

Build

pnpm build

Run in development mode

pnpm dev
`

$3

| Script | Description |
| ------------------- | ---------------------------- |
| pnpm build | Build the project with SWC |
| pnpm dev | Run in development mode |
| pnpm start | Run the built server |
| pnpm typecheck | Run TypeScript type checking |
| pnpm lint | Run ESLint |
| pnpm lint:fix | Fix ESLint issues |
| pnpm format | Format code with Prettier |
| pnpm format:check | Check code formatting |

$3

The scripts/oauth-flow.js script provides a convenient way to authenticate:

`bash
node scripts/oauth-flow.js "CLIENT_ID" "CLIENT_SECRET"
`

This script:

1. Starts a local HTTP server on port 9876
2. Opens your browser to Bitbucket's authorization page
3. Handles the OAuth callback
4. Displays the complete MCP configuration with tokens

Troubleshooting

$3

Another process is using the OAuth callback port. Either:

- Close the other application using port 9876
- Wait a moment and try again (previous OAuth attempt may still be running)

`bash


Find and kill the process using port 9876


lsof -ti:9876 | xargs kill -9
`

$3

The OAuth callback URL in your Bitbucket consumer is incorrect. Make sure it's set to:

`
http://localhost:9876/callback
`

$3

Your access token has expired. The server will automatically:

1. Try to refresh using the refresh token
2. If that fails, open the browser for re-authentication

To manually re-authenticate:

`bash
node scripts/oauth-flow.js "YOUR_CLIENT_ID" "YOUR_CLIENT_SECRET"
`

$3

Check that:

1. Your OAuth consumer has the correct permissions
2. Your app password (if using) has the required scopes
3. For app passwords, ensure BITBUCKET_USERNAME is set

$3

1. Verify your ~/.cursor/mcp.json syntax is valid JSON
2. Restart Cursor or reload the window
3. Check the MCP server logs for errors

License

MIT License - Copyright (c) 2025 Lexmata LLC

See LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

Support

- Documentation
- Issues