← Back to directory
A

Atlassian Bitbucket MCP Server

Community
Connect AI to Your Bitbucket Repositories
GitHub source repository ↗
★ 160 Stars Category · Dev Tools Popular Source revision 19b2b386c800
56FMRS · C
Reliability
8/20
Security and permissions
10/20
Maintenance
10/20
Documentation
16/20
Setup experience
12/20

This MCP server connects AI assistants to Bitbucket Cloud, offering comprehensive operations on workspaces, repositories, and pull requests. It provides flexibility through 6 generic REST tools, with JMESPath filtering and TOON format to reduce token usage. Installation is straightforward, supporting multiple AI clients. Note limitations: Bitbucket Cloud only, requires proper credentials and permissions, and carries risks of token costs and accidental mutations. Overall, it's a feature-rich and practical tool for developers looking to integrate AI into their Bitbucket workflow.

Read the FMRS scoring method →

A Node.js/TypeScript MCP server for Atlassian Bitbucket. It enables AI systems (like Claude, Cursor) to interact with workspaces, repositories, and pull requests via the standard MCP interface. Provides 6 generic tools (bb_get, bb_post, bb_put, bb_patch, bb_delete, bb_clone) that can access any Bitbucket Cloud REST API 2.0 endpoint for reading, creating, updating, deleting, and cloning. Supports JMESPath filtering and TOON output format to reduce token consumption. Requires Node.js 18.0.0 or higher and a Bitbucket Cloud account (not Bitbucket Server/Data Center). Authentication uses Atlassian scoped API tokens (recommended, starting with ATATT) or legacy app passwords (deprecated by June 2026).

Tools

bb_get
Perform a GET request to any Bitbucket API endpoint to read data (e.g., list repositories, get PR details).
bb_post
Perform a POST request to any endpoint to create resources (e.g., create a PR, add a comment).
bb_put
Perform a PUT request to any endpoint to replace resources (e.g., update repository description).
bb_patch
Perform a PATCH request to any endpoint for partial updates (e.g., update PR title).
bb_delete
Perform a DELETE request to any endpoint to remove resources (e.g., delete a branch).
bb_clone
Clone a repository locally to a specified directory.

Setup

  1. Obtain Bitbucket credentials: Recommended is an Atlassian API token (create at https://id.atlassian.com/manage-profile/security/api-tokens, select Bitbucket product, configure scopes: repository, workspace (add pullrequest for PR management)), or an app password (legacy, deprecated by June 2026).
  2. Set environment variables: ATLASSIAN_USER_EMAIL and ATLASSIAN_API_TOKEN (recommended) or ATLASSIAN_BITBUCKET_USERNAME and ATLASSIAN_BITBUCKET_APP_PASSWORD (legacy).
  3. Run via npx directly: npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces".
  4. Configure your AI client (e.g., Claude Desktop): add an MCP server entry in claude_desktop_config.json using the npx command and the environment variables above.
  5. Restart the client to use.
claude_desktop_config.json
{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
      "env": {
        "ATLASSIAN_USER_EMAIL": "[email protected]",
        "ATLASSIAN_API_TOKEN": "your_scoped_api_token"
      }
    }
  }
}

Fit and risk

Best for

  • Developers who want AI assistance with code reviews and repository management.
  • Team leads needing quick insights into project status and pull request activity.
  • DevOps engineers automating repository workflows and branch management.
  • Anyone who wants to interact with Bitbucket using natural language.

Not for

  • Users of Bitbucket Server or Data Center (only Bitbucket Cloud is supported).
  • Users needing real-time push or continuous connections (request-response only).
  • Those requiring complex operations beyond the Bitbucket REST API 2.0 scope.
  • Users unwilling to handle JSON or TOON output (default is TOON, can override to JSON).

Required permissions

  • Requires Bitbucket authentication credentials: Atlassian API token (recommended) or app password (legacy).
  • Appropriate permission scopes: repository and workspace for read-only; add pullrequest for PR management.
  • For app passwords: Workspaces: Read, Repositories: Read (add Write for mutations), Pull Requests: Read (add Write for PR management).
  • Local file system write access if you intend to clone repositories.

Risks and side effects

  • Credential exposure: Tokens or passwords stored in environment variables could be accessed by unauthorized parties. Keep them secure and rotate regularly.
  • Data access: The server can access all Bitbucket data you grant permission to, including private repositories. Run only in trusted environments.
  • Token consumption: Unfiltered API responses can be large, leading to high token costs. Always use JMESPath filtering and pagination.
  • Accidental mutations: AI could perform unintended operations via POST/PUT/PATCH/DELETE tools (e.g., merge PR, delete branch). Test in read-only mode first.
  • Dependency risk: Using npx runs the latest version, which may introduce breaking changes. Consider pinning a version.

Troubleshooting

  1. Authentication failed or 403: Check that the token is valid and has the correct scopes (repository, workspace, pullrequest). Verify environment variable names: ATLASSIAN_USER_EMAIL and ATLASSIAN_API_TOKEN, or ATLASSIAN_BITBUCKET_USERNAME and ATLASSIAN_BITBUCKET_APP_PASSWORD.
  2. Resource not found or 404: Ensure the path is case-sensitive and use workspace slug (from URL) not display name. Test with CLI to list workspaces and confirm slugs.
  3. Claude Desktop not showing server: Check config file JSON syntax, restart Claude Desktop completely, and check logs (macOS: ~/Library/Logs/Claude/mcp*.log).
  4. Tools not working: Enable DEBUG=true to see detailed logs, test with CLI first to isolate issues.
  5. npx execution issues: Ensure Node.js version >= 18 and check network connectivity.

Use cases

Ask AI about your code: "What's the latest commit in my main repository?"
Get PR insights: "Show me all open pull requests that need review."
Search your codebase: "Find all JavaScript files that use the authentication function."
Review code changes: "Compare the differences between my feature branch and main."
Manage pull requests: "Create a PR for my new-feature branch."
Automate workflows: "Add a comment to PR #123 with the test results."

Supported clients

Claude DesktopFull support
Cursor AIFull support
Continue.devFull support
ClineFull support