@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
- Go to your Bitbucket workspace:
https://bitbucket.org/{workspace}/workspace/settings/oauth-consumers - Click "Add consumer"
- 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
- Name:
- 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:
- Start a local callback server on port 9876
- Open your browser to Bitbucket's authorization page
- 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:
- Go to Bitbucket: Personal Settings → App passwords
- Click Create app password
- Give it a name and select permissions:
- Account: Read
- Repositories: Read, Write, Admin
- Pull requests: Read, Write
- Issues: Read, Write
- Pipelines: Read, Write
- 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:
- Starts a local HTTP server on port 9876
- Opens your browser to Bitbucket's authorization page
- Handles the OAuth callback
- 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:
- Try to refresh using the refresh token
- 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:
- Your OAuth consumer has the correct permissions
- Your app password (if using) has the required scopes
- For app passwords, ensure
BITBUCKET_USERNAMEis set
Server not loading in Cursor
- Verify your
~/.cursor/mcp.jsonsyntax is valid JSON - Restart Cursor or reload the window
- 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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request