Bitbucket MCP Server

list_branch_commits

Read-only

Retrieve commits from a Bitbucket branch with filtering by author, message, and date range. Supports pagination, merge commit inclusion, and server-side or client-side filters.

Instructions

List commits on a branch. since (as a rev) and include_merge_commits filter server-side; author/until/search and date-valued since filter client-side over a bounded page walk (noted when more pages exist).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "workspace": "<workspace>",
      "repository": "<repository>",
      "branch_name": "<branch_name>"
    },
    "name": "list_branch_commits"
  }
}

Input Schema

Name	Required	Description
`limit`	No	Max results (default 25)
`since`	No	ISO date lower bound, or a commit SHA/ref (exclusive) for a server-side range
`start`	No	Pagination start (default 0)
`until`	No	ISO date upper bound
`author`	No
`search`	No	Substring in commit message
`workspace`	Yes	Project key (e.g., PROJ)
`repository`	Yes	Repository slug
`branch_name`	Yes
`include_build_status`	No	Server only
`include_merge_commits`	No	Default true

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv3.0.1Sep 27, 2026

removedInput schema / properties / author / description

Removed value: -"Filter by author email/username (optional)"

removedInput schema / properties / branch_name / description
```
Removed value: -"Branch name to get commits from"
```

addedInput schema / properties / include_build_status

Added value: +{
+  "description": "Server only",
+  "type": "boolean"
+}

changedInput schema / properties / include_merge_commits / description

Previous value: -"Include merge commits in results (default: true)"New value: +"Default true"

changedInput schema / properties / limit / description

Previous value: -"Maximum number of commits to return (default: 25)"New value: +"Max results (default 25)"

changedInput schema / properties / repository / description

Previous value: -"Repository slug (e.g., \"my-repo\")"New value: +"Repository slug"

changedInput schema / properties / search / description

Previous value: -"Search for text in commit messages (optional)"New value: +"Substring in commit message"

changedInput schema / properties / since / description

Previous value: -"ISO date string - only show commits after this date (optional)"New value: +"ISO date lower bound, or a commit SHA/ref (exclusive) for a server-side range"

changedInput schema / properties / start / description

Previous value: -"Start index for pagination (default: 0)"New value: +"Pagination start (default 0)"

changedInput schema / properties / until / description

Previous value: -"ISO date string - only show commits before this date (optional)"New value: +"ISO date upper bound"

changedInput schema / properties / workspace / description

Previous value: -"Bitbucket workspace/project key (e.g., \"PROJ\")"New value: +"Project key (e.g., PROJ)"

First observedv1.0.0Aug 15, 2025

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only supply readOnlyHint=true, so the description carries real weight and delivers: it discloses which filters execute server-side vs client-side over a bounded page walk, and that truncation is signalled when more pages exist. That is meaningful behavioral context an agent could not derive from the schema. It stops short of describing ordering or what a result row contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences with no filler, and the core purpose is front-loaded ahead of the filtering caveats. The second sentence is compressed to the point of being slightly telegraphic, but every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter tool with no output schema and only a readOnly annotation, the description covers the trickiest semantics (server vs client filtering, page-walk bounds) well. It leaves gaps on result ordering, how limit/start interact with the bounded walk, and what include_build_status returns, which an agent would have to guess.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 82%, so the baseline is 3, but the description adds genuine meaning by clarifying that 'since' doubles as a rev/SHA (exclusive) or an ISO date and that only the rev form is server-side, while author/until/search are applied client-side. That distinction changes how an agent should combine filters and is not spelled out per-parameter in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening clause 'List commits on a branch' gives a specific verb and resource, and the required workspace/repository/branch_name trio is implied by the schema. It does not explicitly name siblings like list_pr_commits or get_commit_detail, so the agent must infer that this is branch-scoped rather than PR-scoped, but the resource is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the description explains filtering mechanics but never says when to pick this over list_pr_commits or get_commit_detail, nor any prerequisites (e.g., that the branch must exist). An agent can reasonably infer 'use for branch history,' but nothing is stated as a selection rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.