Bitbucket Mcp

@lexmata/bitbucket-mcp

[](https://www.npmjs.com/package/@lexmata/bitbucket-mcp) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](https://github.com/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

# 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

Option 1: OAuth 2.0 (Recommended)

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

1. 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:

# 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.

Option 2: App Password (Simple setup)

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

1. Copy the generated password

Configure with your Bitbucket username and the app password:

{
  "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

With OAuth (Recommended)

{
  "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.

With App Password

{
  "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

{
  "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:

{
  "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

OAuth Tokens

• 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

Re-authenticating

If you need to re-authenticate manually:

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

Or delete the token file to trigger re-authentication:

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

Available Tools

Repository Management

| 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 |

Pull Requests

| 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 |

Branches

| 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 |

Commits

| 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 |

Issues

| 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 |

Pipelines

| 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 |

Code Search

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

Files

| 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

List repositories in a workspace

Use the list_repositories tool with workspace "my-workspace"

Create a pull request

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"

Search for code

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

Trigger a pipeline

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

Development

Prerequisites

• Node.js 18+
• pnpm 9+

Setup

# 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

Scripts

| 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 |

OAuth Flow Helper

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

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

"Port 9876 is already in use"

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)

# Find and kill the process using port 9876
lsof -ti:9876 | xargs kill -9

"localhost:9876 returned not found"

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

http://localhost:9876/callback

"Token is invalid or expired"

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:

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

"Authentication failed (401)"

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

Server not loading in Cursor

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](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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Lexmata
• Source: Lexmata/bitbucket-mcp
• License: MIT
• Homepage: https://lexmata.github.io/bitbucket-mcp

Install and usage instructions live in the source repository linked above.