SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI codingmcp-server-atlassian-bitbucket

mcp-server-atlassian-bitbucket

Atlassian Bitbucket Cloud: work with repositories, pull requests, workspaces and code.

Open website

About this tool

Purpose

mcp-server-atlassian-bitbucket is an MCP (Model Context Protocol) server implemented in Node.js/TypeScript, used to connect AI systems (LLMs) to Atlassian Bitbucket Cloud. Through the standard MCP interface, AI assistants can directly interact with workspaces, repositories, and pull requests, integrating AI into version control workflows.

Main Capabilities

This server provides 6 general-purpose tools that can access any Bitbucket API endpoint. All API tools support the following general parameters:

  • path (required): the API endpoint path starting with /; the system automatically adds the /2.0 prefix.
  • queryParams (optional): key-value pairs of query parameters, for example {"pagelen": "25", "page": "2"}.
  • jq (optional): a JMESPath expression used to filter or transform the response; strongly recommended to reduce token consumption.
  • outputFormat (optional): "toon" (default, reduces tokens by 30-60% compared to JSON) or "json".
  • body (required for POST/PUT/PATCH): the request body as a JSON object.

Common API paths cover workspaces and repositories (list workspaces, list repositories, get repository details, list branches, get/delete branches, list commits, get commit details, get file contents), pull requests (list or create PRs, get/update/delete PRs, get PR diff, list/add PR comments, approve or remove approval, request changes, merge PR, decline PR, compare branches or commits), and other resources (issues, downloads, pipelines, deployments).

Usage

Environment requirements: Node.js 18.0.0 or higher; a Bitbucket Cloud account (Bitbucket Server/Data Center is not supported); authentication credentials (Scoped API Token recommended, or legacy App Password).

Obtaining credentials:

Scoped API Token is recommended: go to Atlassian API Tokens, click "Create API token with scopes", select the "Bitbucket" product, select appropriate scopes (read-only: repository, workspace; full functionality: repository, workspace, pullrequest), copy the generated token (starting with ATATT), and use it together with your Atlassian email as the username.

Legacy App Password: go to Bitbucket App Passwords, create an app password, and select permissions (Workspaces: Read; Repositories: Read, add Write if you need AI to create PRs/comments; Pull Requests: Read, add Write if you need PR management). Note that App Passwords will be deprecated by June 2026.

Connecting an AI assistant:

Claude Desktop users: add the configuration in the config file ~/.claude/claude_desktop_config.json (optionally Scoped API Token or legacy App Password); after restarting Claude Desktop, the status bar will show the bitbucket server.

Other AI assistants: most support MCP. Method one (recommended, always the latest version): configure the AI assistant to run npx -y @aashari/mcp-server-atlassian-bitbucket. Method two: after global installation, configure the AI assistant to use the MCP server with STDIO transport. Supported AI assistants include Claude Desktop (officially supported) and any MCP-compatible client.

Alternative configuration: create ~/.mcp/configs.json for system-level configuration. The configuration key also accepts "atlassian-bitbucket", "@aashari/mcp-server-atlassian-bitbucket", or "mcp-server-atlassian-bitbucket".

CLI usage: the CLI mirrors the MCP tools and can be accessed directly in the terminal; all commands return JSON outoutput (non-TOON, TOON is only used in MCP mode). Available commands include get, delete (requires -p/--path mandatory, -q/--query-params optional, --jq optional), post, put, patch (requires -b/--body mandatory), clone (--workspace-slug optional, --repo-slug mandatory, --target-path mandatory).

Debugging: set the DEBUG environment variable to view detailed logs. In MCP mode, logs are written to ~/.mcp/data/@aashari-mcp-server-atlassian-bitbucket.[session-id].log. You can run HTTP mode together with MCP Inspector for interactive debugging.

Use cases

  • Developers who want AI-assisted code review and repository management.
  • Team leads who need to quickly understand project status and pull request activity.
  • DevOps engineers automating repository workflows and branch management.
  • Anyone who wants to interact with Bitbucket through natural language.

Typical examples: ask the AI to "list all repositories in my main workspace", "show all open pull requests that need review", "find all JavaScript files that use the authentication function", "compare my feature branch and main branch", "create a PR for my new feature branch", "add a test results comment to PR #123".

Limitations

  • Only Bitbucket Cloud is supported, Bitbucket Server/Data Center is not supported.
  • Requires Node.js 18.0.0 or higher.
  • Requires valid Bitbucket authentication credentials.
  • Bitbucket App Password will be deprecated before June 2026; Scoped API Token is recommended.
  • Bitbucket Cloud has rate limits; it is recommended to use filtering to reduce calls.
  • Unfiltered API responses can be very large, with high token cost; it is recommended to always use JMESPath filtering.

Cost optimization suggestions

  • Always use JMESPath filtering to extract only the required fields.
  • Use pagination appropriately and set the pagelen query parameter to limitthe results.
  • Explore the schema first, fetch one unfiltered item to see the available fields, then filter subsequent calls.
  • Take advantage of the TOON format, which by default saves 30-60% tokens compared with JSON.
  • Use Bitbucket's q parameter for server-side filtering.
  • When handling large responses, use sparse fieldsets (the fields parameter), pagination, server-side filtering, and JQ post-processing.

Related tools

Browse category