Bitbucket MCP Server Cursor IDE Setup 2026: API Token Config (App Passwords Retired)

How do you set up the Bitbucket MCP server in Cursor? Create a Bitbucket Cloud API token scoped to repositories and pull requests, add a bitbucket block to your mcp.json with that token and your workspace slug, then restart Cursor. Once connected, your AI can read pull requests, check pipeline status, and manage branches without you switching tabs.

If you set this up before mid-2026 using an App Password, it has already stopped working. Bitbucket Cloud app passwords were disabled during a controlled brownout starting June 9, 2026 and fully removed on July 28, 2026 — there is no grace period or workaround past that date. This guide now leads with the API token flow that replaced them. If you're on Bitbucket Server/Data Center, nothing changed for you; Personal Access Tokens were never part of that deprecation.

Quick Reference

What You Can Do With Bitbucket MCP

Once connected, Cursor can:

Prerequisites

Step 1: Create a Bitbucket API Token (Cloud)

App passwords are gone for Bitbucket Cloud — Atlassian stopped issuing new ones on September 9, 2025, ran a controlled brownout from June 9 to July 27, 2026, and removed them completely on July 28, 2026. The replacement is an API token with scopes, created from your personal Atlassian account settings rather than Bitbucket's old App passwords page:

1. Log in to bitbucket.org (or id.atlassian.com — the account settings are shared across Atlassian products)
2. Go to Settings → Atlassian account settings → Security
3. Select Create and manage API tokens → Create API token with scopes
4. Name it cursor-mcp-2026 and set an expiration date — API tokens are expiring credentials by design, unlike the old app passwords, so plan to rotate this before it lapses
5. Choose Bitbucket as the application
6. Assign the permissions your workflow needs — Bitbucket's API token permissions page is the source of truth for exact scope names, since the scope model changed from app passwords' simple checkboxes to Atlassian's newer granular scopes. At minimum you want read/write on repositories and pull requests; add pipelines read if you want build-status checks
7. Click Create and copy the token immediately — like the old app password, it is shown only once

Your workspace slug is visible in your Bitbucket URL: bitbucket.org/YOUR-WORKSPACE/. This step-by-step is Cloud-only; skip to the Server/Data Center section below if you're self-hosted, since Personal Access Tokens there were never affected by this migration.

Step 2: Install the Bitbucket MCP Server

Unlike GitHub or Linear, Atlassian does not publish a single official standalone Bitbucket-only MCP server package — the closest thing to "official" is the OAuth-based Rovo MCP Server covered on the combined Atlassian guide, which bundles Bitbucket with Jira and Confluence rather than shipping it alone. The App Password workflow in this guide uses a community-maintained package instead. Check the package's own README on npm or GitHub before installing anything, since community package names and maintenance status change more often than an official SDK's would:

npm install -g bitbucket-mcp-server

If that exact package name has been renamed or deprecated by the time you're reading this, search npm for bitbucket-mcp — community implementations such as @korfu/bitbucket-mcp cover the same App Password flow with a different package name and are worth comparing on last-publish date and open issues before picking one.

Verify the install:

bitbucket-mcp-server --version

There is no @modelcontextprotocol/server-bitbucket package published under the official MCP organization as of this writing — don't spend time hunting for one.

Step 3: Add to Cursor MCP Config

Open Cursor → Settings → MCP and add the Bitbucket server:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "bitbucket-mcp-server"],
      "env": {
        "BITBUCKET_USERNAME": "your-bitbucket-username",
        "BITBUCKET_APP_PASSWORD": "your-api-token-here",
        "BITBUCKET_WORKSPACE": "your-workspace-slug",
        "BITBUCKET_DEFAULT_REPO": "my-main-repo"
      }
    }
  }
}

The env var name BITBUCKET_APP_PASSWORD is a holdover — most community packages kept the field name for backward compatibility even after the credential type underneath changed to an API token. Paste your API token there; don't go looking for a separate BITBUCKET_API_TOKEN key unless the specific package's README documents one. Check the package's own README before assuming the field name, since not every maintainer handled the rename the same way.

BITBUCKET_DEFAULT_REPO is optional — it sets a default so you don't have to specify the repo on every request.

Restart Cursor to load the new config.

Step 4: Test the Connection

In Cursor chat, try:

List my Bitbucket repositories

Or:

Show me the open pull requests in the backend-api repo

A successful response with real data means you're connected.

Step 5: Practical Workflows

Code review assistance

Read PR #47 in the payments-service repo. Summarize the changes and flag any potential issues I should review before approving.

Pre-commit checks

Before I push this branch, check if there are any open PRs on main that might conflict with my changes to /src/billing/

Branch management

Create a new branch called feature/stripe-webhooks from main in the payments-service repo

Pipeline monitoring

What's the status of the last pipeline run on the main branch of payments-service?

Automated PR creation

I just finished the feature. Create a pull request from feature/stripe-webhooks to main with the title "Add Stripe webhook handling" and a description summarizing the changes in this diff

Bitbucket Server / Data Center Setup

If you're on Bitbucket Server (self-hosted), the config is slightly different:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "bitbucket-mcp-server"],
      "env": {
        "BITBUCKET_TYPE": "server",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com",
        "BITBUCKET_TOKEN": "your-personal-access-token",
        "BITBUCKET_PROJECT_KEY": "PROJ"
      }
    }
  }
}

Personal Access Tokens on Bitbucket Server are found under Profile → Manage Account → Personal Access Tokens.

Bitbucket MCP Server Setup: What It Actually Takes

If you've skimmed a few of these guides across tools, here's the Bitbucket-specific version stripped of filler: one API token with scopes (five minutes, no admin approval needed for your own account), one JSON block with four fields, one restart. No OAuth app to register, no waiting on a Bitbucket admin to whitelist anything — that's the whole reason this setup path stays under 15 minutes even for someone touching Cursor's MCP settings for the first time.

The trade-off is that an API token is a static credential, not a short-lived OAuth grant. Treat it like any other long-lived secret: scope the permissions to what you actually need (Step 1), and rotate it if you ever suspect it leaked into a shared config or a committed .env. Unlike the old App Password, a scoped API token at least limits the blast radius of a leak to whatever scopes you picked at creation, rather than the broader access an App Password's checkbox-based permissions tended to grant.

Combining Bitbucket With Jira and Confluence

Bitbucket, Jira, and Confluence are all part of the Atlassian ecosystem. With all three MCP servers configured, you can do powerful cross-tool workflows:

Find Jira ticket PROJ-892, read the spec in Confluence, check if there's already a branch for it in Bitbucket, and if not, create one called feature/PROJ-892

This is a workflow that normally requires 3 browser tabs. With all three MCP servers, Cursor handles it in one prompt.

See our guides for Jira MCP setup, Confluence MCP setup, and the combined Atlassian MCP bundle.

Troubleshooting

"410 Gone" or a sudden authentication failure on a config that worked for months
This is almost always an App Password hitting the July 28, 2026 removal date. Bitbucket Cloud returns a 410 rather than a generic auth error for calls still using the retired credential type. There's no way to reactivate an app password — generate an API token per Step 1 and swap it into the same BITBUCKET_APP_PASSWORD config field.

"Invalid credentials" error
Make sure you're using an API token (Step 1), not your Atlassian account password and not an old app password — both of the latter are rejected on Bitbucket Cloud as of July 28, 2026. Server/Data Center users should confirm they're using a Personal Access Token, not their login password.

"Repository not found"
Check your workspace slug matches exactly. It's case-sensitive in some configurations.

Pipelines not showing
Pipelines access requires the Pipelines: Read permission on your App Password. Recreate the password with that permission checked.

Slow responses on large repos
The MCP server paginates results. For repos with thousands of files or PRs, add a limit: "Show me the 5 most recent open PRs" rather than "show all open PRs."

App Password works, but only some repos show up
App Passwords inherit whatever the underlying Bitbucket account can already see. If a repo belongs to a different workspace or the account isn't a member of it, it won't appear — check workspace membership before assuming the credential is scoped wrong.

Config copied from an older (2025) tutorial won't connect
The env var names in Step 3 (BITBUCKET_USERNAME, BITBUCKET_APP_PASSWORD, BITBUCKET_WORKSPACE) are unchanged from earlier 2025 guides. If an old config still fails, it's almost always an expired or revoked App Password rather than a schema change — generate a fresh one rather than debugging the JSON.

Using the Atlassian bundle's OAuth route instead of an App Password, and it suddenly stopped connecting
Check the endpoint, not your App Password — this only applies to the OAuth path, not the one in this guide. Atlassian retired the Rovo MCP Server's older /v1/sse endpoint after June 30, 2026, replacing it with /v1/mcp/authv2, as part of a broader OAuth identity provider migration that started May 27, 2026. A saved config from earlier in 2026 pointing at the old endpoint will fail silently rather than with a clear error. See the Atlassian MCP bundle guide for the current endpoint. This guide's App Password method is a completely separate auth path and isn't affected either way.

"429 Too Many Requests" or requests silently timing out on a large workspace
Bitbucket Cloud's API rate limits apply to App Password auth the same way they apply to OAuth. A prompt like "summarize every open PR across the workspace" fans out into one API call per repo, which trips the limit fast on a workspace with dozens of repos. Scope the prompt to a named repo or a small list of repos instead of the whole workspace, and if you're behind a corporate proxy that rewrites or caches responses, rule that out first with curl -u username:app_password https://api.bitbucket.org/2.0/repositories/YOUR-WORKSPACE before assuming the MCP server itself is broken.

When Not to Use This

Be cautious about letting an AI-driven workflow both open and merge pull requests unattended, especially on repos with an auto-deploy pipeline on merge to main. Keep the merge step manual even after automating PR creation and review summaries — a model confidently wrong about "this looks safe to merge" is a bad failure mode to hit in production.

Frequently Asked Questions

Q: Do Bitbucket app passwords still work for the MCP server setup in 2026?
A: No. Atlassian stopped issuing new Bitbucket Cloud app passwords on September 9, 2025, ran a brownout from June 9 to July 27, 2026, and removed app passwords entirely on July 28, 2026. Any config still using one needs an API token from Step 1 instead — the field name in mcp.json (BITBUCKET_APP_PASSWORD) usually stays the same, only the value changes.

Q: Does this work with Bitbucket Cloud, or only Server/Data Center?
A: Both, with different auth. Bitbucket Cloud uses an API token with scopes (Step 1, replacing the retired App Password); Server/Data Center uses a Personal Access Token and BITBUCKET_TYPE: "server" in the config, shown above.

Q: My AI can read PRs but can't create or approve them — why?
A: Check the permissions on your App Password, not the MCP config. Read-only scopes cover browsing; creating or approving PRs needs Pull requests: Write checked when you generated the password.

Q: Can I limit the AI to one specific repository instead of the whole workspace?
A: Set BITBUCKET_DEFAULT_REPO to scope default requests to one repo, but note this is a convenience default, not a hard restriction — the AI can still reference other repos in the workspace if you name them explicitly in a prompt. For an actual access boundary, use an App Password tied to an account that isn't a member of the other repos.

Q: How does this compare to running the Atlassian MCP bundle instead of a dedicated Bitbucket server?
A: The Atlassian MCP bundle covers Jira, Confluence, and Bitbucket from one token and one config entry — simpler if you use all three, but a single revoked token breaks all three at once. A dedicated Bitbucket-only server (this guide) is a better fit if your team doesn't use Jira or Confluence day-to-day.

Q: Pipeline status shows as passing but the actual build failed — what's going on?
A: This is almost always a stale read against a pipeline that re-ran after your first query. Ask again rather than trusting a cached-sounding answer from earlier in the same chat — the MCP server doesn't push live updates into an existing conversation.

Q: Does this setup still apply if I'm on an older 2025 build of Cursor?
A: Yes. The App Password auth flow and the mcp.json fields in this guide haven't changed between Cursor's 2025 and 2026 releases — the only thing worth re-checking on an old config is whether the App Password itself expired, not the JSON structure.

Q: What's the actual Bitbucket MCP server Cursor IDE setup for 2026, start to finish?
A: Four things: create an App Password scoped to repositories, pull requests, and pipelines (Step 1); install the server package (Step 2); add the bitbucket block from Step 3 to mcp.json with your username, password, and workspace slug; restart Cursor. No OAuth app registration, no admin approval step for a personal setup.

Q: Is there a difference between the Bitbucket MCP server and running the full Atlassian bundle for Bitbucket access?
A: Yes — this guide's dedicated server uses a Bitbucket-only App Password, while the Atlassian bundle uses one OAuth grant covering Jira, Confluence, and Bitbucket together. Pick the dedicated server if Bitbucket is the only Atlassian product you actually touch from Cursor.

Q: Is the Bitbucket MCP server Cursor IDE setup for 2025 2026 the same walkthrough, or two different processes?
A: One process, not two. "2025-2026" here means the App Password flow and the mcp.json fields in Step 3 have carried over unchanged from Cursor's 2025 builds into its 2026 releases — you're not choosing between a 2025 method and a 2026 method, you're following one guide that's stayed current across both.

Q: What's the exact bitbucket mcp server cursor ide setup 2026 process, step by step?
A: Create an App Password with Repositories, Pull requests, and Pipelines scopes (Step 1), install the server package (Step 2), add the bitbucket block to mcp.json with your username, password, and workspace slug (Step 3), restart Cursor, then confirm with a read-only prompt like "list my Bitbucket repositories." Server/Data Center swaps the App Password for a Personal Access Token and adds BITBUCKET_TYPE: "server".

Q: Can I check pipeline status through this connection the same way I'd check it in CircleCI?
A: This guide covers Bitbucket Pipelines specifically — the Pipelines: Read scope on your App Password. If your team runs CircleCI instead of (or alongside) Bitbucket Pipelines for some repos, the CircleCI MCP server is a separate connection with its own token, not something this App Password extends to.

Q: I use the Atlassian bundle's OAuth connection for Bitbucket instead of an App Password — did anything change in 2026?
A: Yes, on the endpoint side. Atlassian retired the Rovo MCP Server's /v1/sse endpoint after June 30, 2026, replacing it with /v1/mcp/authv2, alongside a broader OAuth identity provider migration starting May 27, 2026. A config saved before that migration will stop connecting without an obvious error message. This App Password guide's auth path doesn't go through that endpoint at all, so it's unaffected regardless of when you set it up.

Q: Why do requests against a large workspace time out or return 429 errors?
A: Bitbucket Cloud rate-limits the API the same way for App Password auth as it does for OAuth, and a prompt covering the whole workspace fans out into one call per repo. Scope the request to a named repo or a short list of repos rather than asking for a workspace-wide summary, and rule out a corporate proxy rewriting responses before assuming the server is broken.

Summary

The Bitbucket MCP server gives Cursor direct access to your source control workflow — creating branches, reading PRs, checking pipelines, and searching code across your workspace. Setup takes under 15 minutes.

For teams on the full Atlassian stack, pairing this with Jira and Confluence MCP servers — or the combined Atlassian bundle — creates a unified development context that makes AI assistance significantly more accurate and useful.

Related Guides