bitbucket-mcp-service

Bitbucket MCP Server

Bitbucket API integration for Model Context Protocol (MCP) server. This server allows you to read various information from Bitbucket repositories and integrates seamlessly with Claude Desktop and other MCP clients.

Features

• Repository basic information query
• Commit list and detailed information query
• Commit diff query
• Branch and tag list query
• Pull request list query
• File and directory content query
• Support for both public and private repositories
• Configurable default workspace

Installation

Global Installation (Recommended)

npm install -g bitbucket-mcp-service

Using npx (No installation required)

npx bitbucket-mcp-service

Local Installation

npm install bitbucket-mcp-service

2. Bitbucket Authentication Setup

You need to create a Bitbucket App Password:

• Go to Bitbucket account settings
• Select App passwords menu
• Create new App Password (Required permission: Repositories - Read)
• Set environment variables:

export BITBUCKET_USERNAME="your_username"
export BITBUCKET_APP_PASSWORD="your_app_password"
export BITBUCKET_DEFAULT_WORKSPACE="your_default_workspace_url"

3. MCP Client Configuration

Add the following to your Claude Desktop or other MCP client configuration:

Using Global Installation

{
  "mcpServers": {
    "bitbucket": {
      "command": "bitbucket-mcp-service",
      "env": {
        "BITBUCKET_USERNAME": "your_username",
        "BITBUCKET_APP_PASSWORD": "your_app_password",
        "BITBUCKET_DEFAULT_WORKSPACE": "your_default_workspace_url"
      }
    }
  }
}

Using npx

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["bitbucket-mcp-service"],
      "env": {
        "BITBUCKET_USERNAME": "your_username",
        "BITBUCKET_APP_PASSWORD": "your_app_password",
        "BITBUCKET_DEFAULT_WORKSPACE": "your_default_workspace_url"
      }
    }
  }
}

Using Local Installation

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["./node_modules/bitbucket-mcp-service/build/src/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your_username",
        "BITBUCKET_APP_PASSWORD": "your_app_password",
        "BITBUCKET_DEFAULT_WORKSPACE": "your_default_workspace_url"
      }
    }
  }
}

Available Tools

get_repository_info

Query basic information about a repository.

Parameters:

• repo_slug: Repository name/slug
• workspace (optional): Bitbucket workspace name

get_commits

Query commit list.

Parameters:

• repo_slug: Repository name/slug
• workspace (optional): Bitbucket workspace name
• branch (optional): Branch name
• limit (optional): Number of commits to retrieve (default: 10, max: 100)

get_commit_detail

Query detailed information about a specific commit.

Parameters:

• repo_slug: Repository name/slug
• commit_id: Commit hash/ID
• workspace (optional): Bitbucket workspace name

get_commit_diff

Query changes (diff) for a specific commit.

Parameters:

• repo_slug: Repository name/slug
• commit_id: Commit hash/ID
• workspace (optional): Bitbucket workspace name

get_branches

Query branch list in the repository.

Parameters:

• repo_slug: Repository name/slug
• workspace (optional): Bitbucket workspace name

get_tags

Query tag list in the repository.

Parameters:

• repo_slug: Repository name/slug
• workspace (optional): Bitbucket workspace name

get_pull_requests

Query pull request list.

Parameters:

• repo_slug: Repository name/slug
• workspace (optional): Bitbucket workspace name
• state (optional): PR status (OPEN, MERGED, DECLINED, SUPERSEDED)

get_file_content

Query content of a specific file.

Parameters:

• repo_slug: Repository name/slug
• file_path: File path
• workspace (optional): Bitbucket workspace name
• branch (optional): Branch name (default: main)

get_directory_content

Query directory contents.

Parameters:

• repo_slug: Repository name/slug
• workspace (optional): Bitbucket workspace name
• directory_path (optional): Directory path (default: root)
• branch (optional): Branch name (default: main)

Usage Examples

With default workspace configured, you can use in MCP client:

Show recent 20 commits from myrepo: get_commits repo_slug="myrepo" limit=20
Show specific commit details: get_commit_detail repo_slug="myrepo" commit_id="abc123"
Show file content: get_file_content repo_slug="myrepo" file_path="README.md"

Notes

• Bitbucket App Password is required (regular password cannot be used)
• Public repositories can be queried without authentication for some information, but authentication is required for full functionality
• Consider API rate limits when using
• Proper permission management is needed for repositories containing sensitive information

Development

This project is written in TypeScript and uses the MCP SDK.

Clone and Setup

git clone https://github.com/hyodol53/bitbucket-mcp-service.git
cd bitbucket-mcp-service
npm install

Development Commands

# Build the project
npm run build

# Run in development mode
npm run dev

# Run the built server
npm start

Testing

You can test the server using the provided test.http file with REST Client extension in VS Code.

Contributing

• 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

License

MIT License