Skip to content
Bitbucket MCP Server

JMESPath Filtering

All 37 tools support an optional filter parameter that accepts a JMESPath expression. Filtering is applied before format conversion, making it composable with any output_format.

How It Works

Section titled “How It Works”
  1. The tool fetches data from the Bitbucket API
  2. The JMESPath expression in filter is applied to transform the raw response JSON
  3. The transformed result is then formatted according to output_format

This means you can chain filter and output_format freely.

Basic Syntax

Section titled “Basic Syntax”

JMESPath operates on JSON structures. Common patterns:

ExpressionDescription
values[]Iterate over a values array
values[].titleExtract the title field from each item
values[].{a: fieldA, b: fieldB}Project multiple fields into a new object
values[?state=='OPEN']Filter items where state equals OPEN
length(values)Count items in the array

Examples

Section titled “Examples”

Extract PR titles and authors

Section titled “Extract PR titles and authors”
bb_get_pull_requests workspace=myworkspace repo_slug=myrepo \
  filter="values[].{title: title, author: author.display_name}"

Filter to only open PRs

Section titled “Filter to only open PRs”
bb_get_pull_requests workspace=myworkspace repo_slug=myrepo \
  filter="values[?state=='OPEN']"

Extract repository names from a list

Section titled “Extract repository names from a list”
bb_list_repositories workspace=myworkspace \
  filter="values[].full_name"

Combine filter + TOON output format

Section titled “Combine filter + TOON output format”

Get only PR IDs, titles, and states in compact format:

bb_get_pull_requests workspace=myworkspace repo_slug=myrepo \
  output_format=toon \
  filter="values[].{id: id, title: title, state: state}"

Get JSON output of only open PRs

Section titled “Get JSON output of only open PRs”
bb_get_pull_requests workspace=myworkspace repo_slug=myrepo \
  output_format=json \
  filter="values[?state=='OPEN']"

Learning JMESPath

Section titled “Learning JMESPath”