Skip to main content
Glama
SamtheIII

Bitbucket MCP

by SamtheIII

Bitbucket MCP Server

An MCP server that connects Claude Desktop and Claude Code to Bitbucket Cloud, enabling AI-assisted bug triage, impact analysis from live repository data.

Tools

Tool

Description

search_by_jira_id

Find PRs (by title/branch) and commits (by message) linked to a Jira issue key. Searches one repo or all repos in the workspace.

search_by_pr_title

Search PRs by keyword — returns details, description, comments, and changed files in one response

get_changed_files

List modified files with line add/remove counts for a PR number or commit hash

get_diff

Return the full unified diff for a PR or commit, truncated at a line boundary if over 50,000 characters

get_file_content

Return the full content of a file at a given branch or commit ref

get_commit_history_for_file

Show commit history for a file — frequency, authors, and dates

get_related_prs

Find other PRs that touched the same files as a given PR or commit

list_repos

List all repositories in the configured workspace

Related MCP server: Atlassian Bitbucket MCP Server

Authentication

Bitbucket Cloud uses Basic Auth with a Bitbucket API Token

  1. Go to Bitbucket -> Account Settings -> Security -> API Tokens

  2. Create a Token with Scope

Quick setup (Windows)

Run the setup script — it installs dependencies, builds, prompts for credentials, and registers the server in both Claude Desktop and Claude Code:

powershell -ExecutionPolicy Bypass -File setup.ps1

Credentials are written to .env.local (git-ignored). The MCP config entry stays secret-free.

Manual setup

1. Install and build

npm install
npm run build

2. Create .env.local

BITBUCKET_WORKSPACE=https://bitbucket.org/your-workspace/workspace/overview/
BITBUCKET_EMAIL=you@example.com
BITBUCKET_API_TOKEN=your_app_password_here

3. Register in Claude Desktop

Open %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) and add:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["C:/path/to/bitbucket-mcp-server/dist/index.js"]
    }
  }
}

Restart Claude Desktop to load the tools.

4. Register in Claude Code

claude mcp add bitbucket node "C:/path/to/bitbucket-mcp-server/dist/index.js" --scope user

Environment variables

Variable

Required

Description

BITBUCKET_WORKSPACE

Yes

Full workspace URL or slug (e.g. my-workspace)

BITBUCKET_EMAIL

Yes

Your Atlassian account email

BITBUCKET_API_TOKEN

Yes

Bitbucket App Password (from account → App passwords)

Example prompts

"Show me all PRs and commits related to PROJ-123"
"Search PRs mentioning login timeout in repo my-service"
"What files were changed in PR 42 in repo my-service?"
"Get the diff for commit a1b2c3d4 in repo my-service"
"Show me the content of src/auth.ts on the main branch"
"Who has been changing src/payment/processor.ts and how often?"
"Find other PRs that touched the same files as PR 42"
"List all repos in the workspace"

Available Tools

8 tools
get_changed_filesB

Get the list of files changed in a pull request or commit, with per-file line add/remove counts.

ParametersJSON Schema
NameRequiredDescriptionDefault
refYesPR number (e.g. "42") or commit hash (e.g. "a1b2c3d4")
repoSlugYesRepository slug (e.g. my-repo)

TDQS

B3.4/5.0
Behavior2/5

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

With no annotations, the description carries full burden for behavioral disclosure. It does not state that the tool is read-only, safe, or any potential side effects. While the operation is clearly a read, the lack of explicit safety information leaves gaps for the agent.

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

Conciseness5/5

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

The description is a single sentence of 20 words, directly front-loading the action. Every word adds value; no fluff or repetition. Ideal conciseness.

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

Completeness4/5

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

For a simple list tool, the description provides enough context: input (PR/commit) and output (file list with add/remove counts). The absence of an output schema is partially compensated. However, missing details like pagination or error cases prevent a perfect score.

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

Parameters3/5

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

Schema coverage is 100%, so baseline is 3. The description does not add additional meaning beyond the schema's parameter descriptions (ref and repoSlug are already well-documented). No extra value is provided.

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

Purpose5/5

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

The description clearly states the verb 'Get', the resource 'list of files changed', and the scope ('pull request or commit') with explicit output ('per-file line add/remove counts'). It distinguishes itself from sibling tools like get_diff (full diff) and get_file_content (file content), making the purpose unambiguous.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives (e.g., get_diff). The description only states what it does, leaving the agent to infer the use case without explicit when/when-not instructions.

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

get_commit_history_for_fileB

Get the commit history for a specific file, showing who changed it and how frequently.

ParametersJSON Schema
NameRequiredDescriptionDefault
filePathYesPath to the file within the repository (e.g. src/auth.ts)
repoSlugYesRepository slug (e.g. my-repo)
limitNoMaximum number of commits to return (default 50)

TDQS

B3.2/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It only states what the tool does but does not disclose ordering, pagination, or performance implications.

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

Conciseness5/5

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

The description is a single, efficient sentence with no wasted words.

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

Completeness2/5

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

Without an output schema, the description only vaguely mentions 'who changed it and how frequently', lacking specifics on output fields, ordering, and default limit behavior.

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

Parameters3/5

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

Schema coverage is 100% with clear descriptions for all parameters; the description adds no additional semantics beyond the schema.

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

Purpose5/5

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

The description clearly states the verb 'Get' and the resource 'commit history for a specific file', and distinguishes the tool from siblings by focusing on file-specific history.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use or not use this tool versus alternatives like get_diff or get_changed_files.

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

get_diffA

Get the full unified diff for a pull request or commit. Diffs larger than 50,000 characters are truncated at a line boundary.

ParametersJSON Schema
NameRequiredDescriptionDefault
refYesPR number (e.g. "42") or commit hash (e.g. "a1b2c3d4")
repoSlugYesRepository slug (e.g. my-repo)

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden. It discloses a key behavior: truncation at 50,000 characters at a line boundary. However, it omits other potential traits such as permissions required, rate limits, or response format beyond the name hint.

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

Conciseness5/5

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

Two concise sentences, no wasted words. The key information about truncation is included and front-loaded.

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

Completeness4/5

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

Given the tool's simplicity (2 required params, no output schema, no nested objects), the description adequately covers purpose and a critical behavioral trait. Could mention that output is a unified diff string, but not essential.

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

Parameters3/5

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

Schema coverage is 100%, with both parameters described in the schema (ref as PR number or commit hash, repoSlug as repo slug). The description adds no additional meaning beyond what the schema already provides.

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

Purpose5/5

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

The description clearly states the verb 'Get' and resource 'full unified diff for a pull request or commit'. It distinguishes from siblings like get_changed_files which list changed files rather than the unified diff.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives such as get_changed_files or get_file_content. The description does not indicate prerequisites or context for using this tool.

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

get_file_contentA

Get the full content of a file at a given branch name or commit hash. If no ref is given, the repository's default branch is used.

ParametersJSON Schema
NameRequiredDescriptionDefault
filePathYesPath to the file within the repository (e.g. src/auth.ts)
refNoBranch name or commit hash (defaults to the repo's main branch)
repoSlugYesRepository slug (e.g. my-repo)

TDQS

A3.7/5.0
Behavior2/5

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

No annotations exist, so the description must fully convey behavioral traits. It only states the basic function and default ref behavior, but fails to mention whether the operation is read-only, return format (e.g., raw text), size limitations, or error handling. This is insufficient for transparent selection.

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

Conciseness5/5

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

Two sentences with no extraneous information. The action and scope are front-loaded. Every word is purposeful.

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 a simple file retrieval tool with three parameters and no output schema, the description covers the primary behavior and parameter defaults. However, it lacks information about output format, error scenarios, or size limits, which would be helpful for an AI agent without external context.

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?

The input schema already provides descriptions for all three parameters (100% coverage). The description adds value by clarifying that the 'ref' parameter defaults to the repository's default branch, which is not in the schema. This enhances parameter understanding.

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

Purpose5/5

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

The description clearly states the tool retrieves the full content of a file at a specified branch or commit hash, defaulting to the repository's default branch. This is distinct from sibling tools like get_diff or get_changed_files which focus on changes.

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?

The description implies usage for reading file contents but does not explicitly state when to use this tool over alternatives such as get_changed_files or get_diff. No when-not-to-use guidance is provided.

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

list_reposB

List all repositories in the configured Bitbucket workspace.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of repositories to return (omit to get all)

TDQS

B3.3/5.0
Behavior2/5

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

No annotations exist, so the description must disclose behavioral traits. It only mentions listing and an optional limit, but does not specify whether the operation is read-only, whether pagination occurs, or any prerequisites like workspace configuration.

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

Conciseness5/5

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

The description is a single sentence with no wasted words. It is front-loaded with the essential action and resource.

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?

Given the tool's simplicity (one optional parameter, no output schema), the description provides the minimum viable information. However, it lacks behavioral context and usage guidance, making it slightly incomplete.

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

Parameters3/5

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

Schema coverage is 100% and the single parameter `limit` has a clear description in the schema. The description adds no additional meaning beyond that, so a baseline score of 3 is appropriate.

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

Purpose5/5

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

The description clearly states the verb (List), the resource (repositories), and the scope (in the configured Bitbucket workspace). It is specific enough to distinguish from sibling tools that deal with files, commits, diffs, PRs, or search.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives like search_by_pr_title or get_changed_files. There is no mention of typical use cases or when not to use it.

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

search_by_jira_idA

Search Bitbucket for PRs and commits related to a Jira issue ID. Finds PRs where the ID appears in the title or source branch name, and commits where it appears in the message.

ParametersJSON Schema
NameRequiredDescriptionDefault
jiraIdYesJira issue key (e.g. PROJ-123)
repoSlugNoRepository slug — omit to search all repos in the workspace

TDQS

A3.8/5.0
Behavior3/5

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

No annotations provided; description discloses where the search looks (title, branch, commit message) but lacks detail on authorization, rate limits, or behavior when no matches are found.

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

Conciseness5/5

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

Two sentences, no wasted words, front-loaded with purpose. Every sentence adds value.

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

Completeness4/5

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

No output schema, but tool's return format is implicit. Description is mostly complete for a simple search tool with two parameters; could mention result format.

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

Parameters3/5

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

Schema description coverage is 100%; both parameters are described in the schema. The description adds minimal additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

Purpose5/5

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

Description clearly states the tool searches Bitbucket for pull requests and commits related to a Jira issue ID, specifying where the ID appears (title, source branch, commit message). It distinguishes from sibling 'search_by_pr_title' by focusing on Jira ID rather than PR title.

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?

Description implies usage when a Jira ID is known, but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like 'search_by_pr_title' or other search tools.

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

search_by_pr_titleA

Search pull requests by keyword in the title. Returns PR details, description, comments, and changed files.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesKeyword(s) to search for in PR titles
repoSlugYesRepository slug (e.g. my-repo)
stateNoPR state filter (default: ALL)
limitNoMax PRs to return, including their comments and changed files (default 10, max 25)

TDQS

A3.5/5.0
Behavior2/5

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

No annotations exist, so the description carries the full burden. It discloses return content but does not mention that the operation is read-only, any required authentication, rate limits, or pagination behavior.

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

Conciseness5/5

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

Two concise sentences that front-load the core purpose and immediately follow with the return value summary, with no extraneous words.

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?

Given 4 parameters and no output schema or annotations, the description provides minimal completeness—it explains what is returned but lacks detail on filtering or usage edge cases.

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

Parameters3/5

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

Schema coverage is 100% with all parameters described, and the description adds no further parameter semantics. Baseline score of 3 is appropriate.

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

Purpose5/5

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

The description uses a specific verb 'Search' and resource 'pull requests by keyword in the title', clearly stating the tool's function and listing return content (PR details, description, comments, changed files), distinguishing it from siblings like get_changed_files or get_related_prs.

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?

The description implies usage for searching by title keyword but provides no explicit guidance on when to use or avoid, nor mentions alternatives among sibling tools.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 8 tool updatesv1.0.0
    • First observedget_changed_files
    • First observedget_commit_history_for_file
    • First observedget_diff
    • First observedget_file_content
    • First observedget_related_prs
    • First observedlist_repos
    • First observedsearch_by_jira_id
    • First observedsearch_by_pr_title

TDQS

A3.7/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: get_changed_files, get_commit_history_for_file, get_diff, get_file_content, get_related_prs, list_repos, search_by_jira_id, search_by_pr_title. No two tools overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_changed_files, list_repos, search_by_jira_id). The verbs (get, list, search) and nouns are clear and predictable.

Tool Count5/5

With 8 tools, the server is well-scoped for its purpose. It covers essential Bitbucket operations without being too sparse or overwhelming.

Completeness3/5

The tool set lacks fundamental PR operations such as listing PRs, getting a single PR by ID, creating or updating PRs, and commenting. It is read-only and focused on code review and searching, but missing basic CRUD for PRs is a notable gap.

Maintenance

ActivityStale
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/SamtheIII/Bitbucket-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server