bitbucket-mcp-server

zenvite2/bitbucket-mcp-server

3.1

If you are the rightful owner of bitbucket-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This is an MCP server implementation for connecting to a self-hosted Bitbucket Server instance, providing various functionalities over stdio.

Tools
12
Resources
0
Prompts
0

Bitbucket MCP Server

This is an MCP (Model Context Protocol) server implementation that connects to a self-hosted Bitbucket Server instance. The server communicates over stdio and can be integrated with MetaMCP.

Overview

This server provides access to Bitbucket Server functionality including:

  • Project and repository management
  • File browsing and content retrieval
  • Branch, commit, and pull request management
  • User and permissions management
  • Repository search capabilities

The server connects to http://bitbucket.digital.vn (a self-hosted Bitbucket Server instance, not Bitbucket Cloud) using the Atlassian Python API library.

Features

  1. Connection to Self-Hosted Bitbucket Server

    • Connects to http://bitbucket.digital.vn (not Bitbucket Cloud)
    • Uses official Atlassian Python API instead of manual HTTP requests
    • Supports multiple authentication methods (username/password, token)

  2. Project and Repository Retrieval

    • Get list of projects from Bitbucket Server
    • Get repositories for a specific project
    • Proper handling of paginated responses from the API

  3. Repository File Browsing

    • Browse repository files and directories
    • Get content of specific files
    • Navigate through repository structure

  4. Repository History and Branches

    • Get list of branches in a repository
    • Get commit history for repositories
    • Access to specific commits and their details

  5. Pull Request Management

    • Get list of pull requests in a repository
    • Retrieve details of specific pull requests
    • Filter pull requests by state (OPEN, MERGED, DECLINED)

  6. User and Permissions Management

    • Get users within a project
    • Retrieve project permissions for groups and users
    • View access controls and permission levels

  7. Repository Search

    • Search for repositories by name, slug, or description
    • Find repositories across all projects

  8. MCP Server Integration

    • Streaming stdio-based MCP server using FastMCP
    • Proper stdio-based communication following MCP protocol
    • Configuration-ready for MetaMCP integration
    • Works as a standard MCP server

Project Structure

bitbucket-mcp-server/
├── src/
│   ├── __init__.py
│   ├── main.py              # Main application entry point
│   ├── bitbucket_client.py  # Bitbucket client implementation
│   └── config.py            # Configuration management
├── tests/
│   ├── __init__.py
│   ├── conftest.py          # Pytest configuration
│   └── test_bitbucket_client.py
│   └── test_connection.py   # Connection testing script
├── setup.sh                 # Script to install dependencies and setup environment
├── test.sh                  # Standalone test suite for functionality verification
├── pyproject.toml           # Project metadata and dependencies
├── uv.lock                  # Dependency lock file
├── .env.example            # Example environment variables
└── README.md               # Project documentation

Dependencies

  • fastmcp: FastMCP framework for building MCP servers
  • atlassian-python-api: Client library for Atlassian products
  • requests: HTTP library for making requests
  • pydantic-settings: Configuration management

Setup and Usage

Prerequisites

  1. Install UV package manager for dependency management
  2. Ensure you have Python 3.10+ installed

Environment Configuration

  1. Copy the example environment file:

    cp .env.example .env

  2. Edit the .env file with your Bitbucket Server credentials:

    # Update these values in .env
BITBUCKET_URL=http://bitbucket.digital.vn
BITBUCKET_USERNAME=your-username
BITBUCKET_PASSWORD=your-password
# Or use a token-based authentication
# BITBUCKET_TOKEN=your-token

Installation

  1. Install dependencies using the setup script: 
    ./setup.sh install

Testing

  1. Test the connection to Bitbucket Server:

    ./setup.sh test-connection

  2. Run the test suite:

    ./setup.sh test
# Or run standalone tests
./test.sh

Running the Server

  1. Start the MCP server: 
    uv run python src/main.py

The server runs as a stdio-based MCP server and connects to your configured Bitbucket Server instance.

MetaMCP Configuration

To use this server with MetaMCP, add the following configuration (update the path to match your home directory):

{
  "mcpServers": {
    "bitbucket-mcp": {
      "type": "STDIO",
      "command": "/home/[YOUR_USERNAME]/ai-workspace/bitbucket-mcp-server/.venv/bin/python",
      "args": [
        "/home/[YOUR_USERNAME]/ai-workspace/bitbucket-mcp-server/src/main.py"
      ]
    }
  }
}

This configuration uses the virtual environment's Python interpreter which already has all the required dependencies installed.

Available Tools

  1. connection_status - Check the connection status to Bitbucket
  2. get_projects - Get list of projects from Bitbucket
  3. get_repositories - Get repositories for a specific project (requires project_key parameter, optional start and limit for pagination)
  4. get_repository_files - Get files in a specific repository path (requires project_key, repository_slug, optional path, start and limit for pagination)
  5. get_file_content - Get content of a specific file in a repository (requires project_key, repository_slug, filename)
  6. get_branches - Get branches in a specific repository (requires project_key, repository_slug, optional start and limit for pagination)
  7. get_commits - Get commits in a specific repository (requires project_key, repository_slug, optional until, start and limit for pagination)
  8. get_pull_requests - Get pull requests in a specific repository (requires project_key, repository_slug, optional state, start and limit for pagination)
  9. get_pull_request - Get a specific pull request (requires project_key, repository_slug, pull_request_id)
  10. get_users - Get users in Bitbucket, optionally filtered by project (optional project_key, start and limit for pagination)
  11. get_project_permissions - Get permissions for a specific project (requires project_key, optional groups_start, groups_limit, users_start, users_limit for pagination)
  12. search_repositories - Search for repositories by name or description (requires search_query, optional start and limit for pagination)

Configuration

The application can be configured using environment variables in the .env file:

  • BITBUCKET_URL: URL of the Bitbucket Server (default: http://bitbucket.digital.vn)
  • BITBUCKET_USERNAME: Username for authentication (optional)
  • BITBUCKET_PASSWORD: Password for authentication (optional)
  • BITBUCKET_TOKEN: Token for authentication (optional)

Testing

Run the tests with:

./setup.sh test
# or
uv run pytest tests/ -v

Development

The project uses UV for dependency management. To work on this project:

  1. Install dependencies: uv sync
  2. Run in development mode: uv run python src/main.py
  3. Run tests: uv run pytest tests/ -v