scm-broker-mcp
Provides tools for Bitbucket Cloud pull-request workflows, including listing repositories and pull requests, retrieving diffs and commits, creating and updating pull requests, adding comments, and merging or closing pull requests where supported.
Provides tools for GitHub pull-request workflows, including listing repositories and pull requests, retrieving diffs and commits, creating and updating pull requests, managing reviewers, adding comments, and merging or closing pull requests.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@scm-broker-mcp Show open pull requests for acme/widgets on GitHub"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
scm-broker-mcp
A provider-neutral MCP server for pull-request workflows on GitHub and Bitbucket Cloud. It uses the official Python MCP SDK and supports Streamable HTTP plus stdio.
Getting started
uv sync --dev
export GITHUB_TOKEN='…' # only if using GitHub
export BITBUCKET_EMAIL='you@example.com' # only if using Bitbucket
export BITBUCKET_API_TOKEN='…'
uv run scm-broker-mcp-http # http://127.0.0.1:8000/mcp
# or: uv run scm-broker-mcp-stdioThe fourteen tools accept provider (github or bitbucket), repo (owner/name or workspace/slug), and operation-specific fields. Results have stable id, state, url, pagination, and optional raw fields. Credentials are never tool arguments or logs. Configure authentication at a reverse proxy before exposing the HTTP endpoint beyond localhost.
Related MCP server: Bitbucket MCP Server
Tools
list_repositories, list_pull_requests, get_pull_request, get_pull_request_diff, list_pull_request_commits, create_pull_request, update_pull_request, update_pull_request_reviewers, close_pull_request, merge_pull_request, add_pull_request_comment, list_pull_request_comments, list_pull_request_reviews, and submit_pull_request_review.
Bitbucket Cloud does not provide the same reviewer-update and review-submission semantics as GitHub; unsupported capabilities return structured unsupported_operation errors. Provider permissions and branch rules still apply.
Container deployment
Build from source without secrets:
FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
WORKDIR /app
COPY . .
RUN uv sync --no-dev && useradd --uid 10001 --system broker
USER 10001
ENTRYPOINT ["uv", "run", "--no-dev", "scm-broker-mcp-http"]Inject credentials at runtime, never into the image, source tree, files, URLs, or command line. Run as a dedicated non-root UID with a read-only root filesystem and dropped capabilities. Keep untrusted agents away from the server container's filesystem, process namespace, and secret-bearing environment. This assumes the deployment platform enforces container separation; environment credentials do not protect against a privileged agent sharing the container or host. Bind to localhost by default and use an authenticated reverse proxy for remote access.
Recent Features
Date | Purpose | Spec | Author |
2026-09-13-17-39 | Scoped pull-request MCP server | whose-footprints-are-these |
Repo Structure
src/scm_broker_mcp/ # server, service, schemas, provider adapters
tests/ # mocked contract and protocol tests
docs/features/ # approved feature specificationsDevelopment
uv run pytest
uv build
uv lock --check
git diff --checkContributing
This is an AI-first repository. Read AGENTS.md, use a reviewed feature specification, work on a focused branch, and follow test-driven development. Do not commit credentials or generated environments.
Available Tools
14 toolsadd_pull_request_commentB
Add a comment to a pull request.
Args: provider: Provider key. repo: Repository identity. pull_request_id: Provider pull-request identifier. body: Comment text. raw: Include the provider payload.
Returns: Normalized write-result mapping.
Examples:
Input: {"repo": "o/r", "pull_request_id": "7", "body": "Looks good"}.
Output: {"id": "comment-1", "state": "", ...}.
Inputs: body (required), repo (required), provider (required), pull_request_id (required), +1 more. Returns: object
close_pull_requestB
Close or decline a pull request.
Args: provider: Provider key. repo: Repository identity. pull_request_id: Provider pull-request identifier. raw: Include the provider payload.
Returns: Normalized write-result mapping with the resulting state.
Examples:
Input: {"repo": "o/r", "pull_request_id": "7"}.
Output: {"id": "7", "state": "closed", ...}.
Inputs: repo (required), provider (required), pull_request_id (required), raw. Returns: object
create_pull_requestB
Create a pull request from one branch into another.
Args: provider: Provider key. repo: Repository identity. title: Pull-request title. source_branch: Source branch name. target_branch: Destination branch name. description: Optional body text. raw: Include the provider payload.
Returns: Normalized write-result mapping with identifier, state, and URL fields.
Examples:
Input: {"repo": "o/r", "title": "Fix", "source_branch": "bug", "target_branch": "main"}.
Output: {"id": "8", "state": "open", "url": "https://...", ...}.
Inputs: repo (required), title (required), provider (required), source_branch (required), +3 more. Returns: object
get_pull_requestA
Get one pull request.
Args: provider: Provider key. repo: Repository identity. pull_request_id: Provider pull-request identifier. raw: Include the provider payload.
Returns:
Normalized pull-request mapping with id, title, state, and url.
Examples:
Input: {"provider": "github", "repo": "o/r", "pull_request_id": "7"}.
Output: {"id": "7", "title": "Fix", "state": "open", ...}.
Inputs: repo (required), provider (required), pull_request_id (required), raw. Returns: object
get_pull_request_diffB
Get a pull request unified diff.
Args: provider: Provider key. repo: Repository identity. pull_request_id: Provider pull-request identifier.
Returns:
Mapping shaped as {"diff": str, "raw": None}.
Examples:
Input: {"provider": "github", "repo": "o/r", "pull_request_id": "7"}.
Output: {"diff": "diff --git ...", "raw": None}.
Inputs: repo (required), provider (required), pull_request_id (required). Returns: object
list_pull_request_commentsA
List comments attached to a pull request.
Args: provider: Provider key. repo: Repository identity. pull_request_id: Provider pull-request identifier. page: One-based page number. page_size: Number of results, from 1 through 100. raw: Include provider payloads.
Returns: Page mapping containing normalized comment items.
Examples:
Input: {"repo": "o/r", "pull_request_id": "7", "page": 1}.
Output: {"items": [{"id": "comment-1", ...}], ...}.
Inputs: repo (required), provider (required), pull_request_id (required), raw, +2 more. Returns: object
list_pull_request_commitsB
List commits associated with a pull request.
Args:
provider: Provider key; repo and pull_request_id identify the PR.
page: One-based page number.
page_size: Number of results, from 1 through 100.
raw: Include provider payloads.
Returns: Page mapping containing normalized commit items.
Examples:
Input: {"provider": "github", "repo": "o/r", "pull_request_id": "7"}.
Output: {"items": [{"id": "abc", ...}], "page": 1, ...}.
Inputs: repo (required), provider (required), pull_request_id (required), raw, +2 more. Returns: object
list_pull_request_reviewsA
List reviews attached to a pull request.
Args: provider: Provider key. repo: Repository identity. pull_request_id: Provider pull-request identifier. page: One-based page number. page_size: Number of results, from 1 through 100. raw: Include provider payloads.
Returns: Page mapping containing normalized review items.
Examples:
Input: {"repo": "o/r", "pull_request_id": "7", "page": 1}.
Output: {"items": [{"id": "review-1", ...}], ...}.
Inputs: repo (required), provider (required), pull_request_id (required), raw, +2 more. Returns: object
list_pull_requestsA
List pull requests in a repository.
Args:
provider: Provider key.
repo: Repository in owner/name or workspace/slug form.
state: Provider pull-request state filter.
page: One-based page number.
page_size: Number of results, from 1 through 100.
raw: Include provider payloads.
Returns: Page mapping with normalized pull-request items.
Examples:
Input: {"provider": "github", "repo": "o/r", "state": "open"}.
Output: {"items": [{"id": "7", "state": "open", ...}], ...}.
Inputs: repo (required), provider (required), raw, page, +2 more. Returns: object
list_repositoriesA
List repositories visible to the authenticated provider account.
Args:
provider: "github" or "bitbucket".
workspace: Optional Bitbucket workspace or GitHub repository scope.
page: One-based page number.
page_size: Number of results, from 1 through 100.
raw: Include provider payloads.
Returns:
Page mapping with items, page, page_size, and has_more.
Examples:
Input: {"provider": "github", "page": 1, "page_size": 30}.
Output: {"items": [{"id": "1", ...}], "page": 1, "page_size": 30, "has_more": False}.
Inputs: provider (required), raw, page, page_size, +1 more. Returns: object
merge_pull_requestA
Merge a pull request using an explicit provider-supported method.
Args:
provider: Provider key.
repo: Repository identity.
pull_request_id: Provider pull-request identifier.
merge_method: One of merge, squash, or rebase.
raw: Include the provider payload.
Returns: Normalized write-result mapping with resulting state and URL.
Examples:
Input: {"repo": "o/r", "pull_request_id": "7", "merge_method": "squash"}.
Output: {"id": "7", "state": "merged", ...}.
Inputs: repo (required), provider (required), pull_request_id (required), raw, +1 more. Returns: object
submit_pull_request_reviewA
Submit an approve, request-changes, or comment review.
Args:
provider: Provider key.
repo: Repository identity.
pull_request_id: Provider pull-request identifier.
event: approve, request_changes, or comment.
body: Optional review body.
raw: Include the provider payload.
Returns: Normalized write-result mapping, or a structured error mapping.
Examples:
Input: {"repo": "o/r", "pull_request_id": "7", "event": "approve"}.
Output: {"id": "7", "state": "approved", ...} or an error shape.
Inputs: repo (required), event (required), provider (required), pull_request_id (required), +2 more. Returns: object
update_pull_requestA
Update a pull-request title or description.
Args: provider: Provider key. repo: Repository identity. pull_request_id: Provider pull-request identifier. title: Optional replacement title. description: Optional replacement body. raw: Include the provider payload.
Returns: Normalized write-result mapping.
Examples:
Input: {"repo": "o/r", "pull_request_id": "7", "title": "Updated"}.
Output: {"id": "7", "title": "Updated", "state": "open", ...}.
Inputs: repo (required), provider (required), pull_request_id (required), raw, +2 more. Returns: object
update_pull_request_reviewersB
Request reviewers when supported by the provider.
Args: provider: Provider key. repo: Repository identity. pull_request_id: Provider pull-request identifier. reviewers: Reviewer usernames or account identifiers.
Returns: Normalized provider write-result mapping.
Examples:
Input: {"repo": "o/r", "pull_request_id": "7", "reviewers": ["alice"]}.
Output: {"id": "7", "state": "", "raw": None, ...}.
Inputs: repo (required), provider (required), reviewers (required), pull_request_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct resource-action pair: repository listing versus pull request listing, and PR-specific tools are cleanly separated by diff, commits, comments, reviews, close, merge, and reviewer assignment. Even similar operations like update_pull_request_reviewers and submit_pull_request_review are unambiguous from their names and arguments.
All tool names follow a consistent verb_noun snake_case pattern using list_, get_, create_, update_, close_, merge_, add_, and submit_. The plural/singular variations are grammatical and predictable, making the API easy to navigate.
14 tools is a well-scoped size for an SCM broker covering repository discovery and full pull request workflows. Every tool serves a meaningful purpose without redundancy or filler.
The pull request lifecycle is thoroughly covered: reading, creating, updating, closing, merging, commenting, and reviewing. The repository side is thin (only list_repositories, no get/create), and comments/reviews lack update/delete operations, but these are minor gaps agents can work around.
Maintenance
Related MCP Connectors
Manage repositories, users, releases, and automate GitHub workflows
Operate GitHub from your AI assistant: repos, PRs, issues, Actions. Previews and read-only mode.
A Model Context Protocol (MCP) application for automated GitHub PR analysis and issue management.…
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables management of Bitbucket Cloud pull requests through natural language, including creating, reviewing, approving, and commenting on PRs with automatic default reviewer support.791MIT
- AlicenseAqualityCmaintenanceEnables retrieval of pull request metadata and diffs from Bitbucket Cloud and Server/Data Center, with optional comment creation.31MIT
- FlicenseAqualityDmaintenanceEnables analysis of GitHub Pull Requests, including details, diff, file lists, and review tracking.3-
- AlicenseNot gradedqualityCmaintenanceEnables pull-request review workflows on Bitbucket Cloud via Claude Code, offering tools to view PR metadata, comments, diffs, and to post comments or approve.6,189 npmMIT