MCP (Model Context Protocol) server for Bitbucket Cloud - 25+ tools for repositories, pull requests, branches, commits, issues, pipelines, and code search
npm install @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.
- 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
``bashUsing npm
npm install -g @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-mcpInstall dependencies
pnpm installBuild
pnpm buildRun 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 errorsLicense
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`)