Transform how you work with Bitbucket by connecting Claude, Cursor AI, and other AI assistants directly to your repositories, pull requests, and code. Get instant insights, automate code reviews, and streamline your development workflow.
Node.js/TypeScript MCP server for Atlassian Bitbucket. Enables AI systems (LLMs) to interact with workspaces, repositories, and pull requests via tools (list, get, comment, search). Connects AI directly to version control workflows through the standard MC
2026-11-17
星數
—
工具
—
可用率
—
What You Can Do
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"
Perfect 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
Repositories: Read (and Write if you want AI to create PRs/comments)
Pull Requests: Read (and Write for PR management)
2. Try It Instantly
# Set your credentials (choose one method)
# Method 1: Scoped API Token (recommended - future-proof)
export ATLASSIAN_USER_EMAIL="[email protected]"
export ATLASSIAN_API_TOKEN="your_scoped_api_token" # Token starting with ATATT
# OR Method 2: Legacy App Password (will be deprecated June 2026)
export ATLASSIAN_BITBUCKET_USERNAME="your_username"
export ATLASSIAN_BITBUCKET_APP_PASSWORD="your_app_password"
# List your workspaces
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"
# List repositories in a workspace
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace"
# Get pull requests for a repository
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace/your-repo/pullrequests"
# Get repository details with JMESPath filtering
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace/your-repo" --jq "{name: name, language: language}"
Connect to AI Assistants
For Claude Desktop Users
Add this to your Claude configuration file (~/.claude/claude_desktop_config.json):
Option 1: Scoped API Token (recommended - future-proof)
Alternative config keys: The system also accepts "atlassian-bitbucket", "@aashari/mcp-server-atlassian-bitbucket", or "mcp-server-atlassian-bitbucket" instead of "bitbucket".
Available Tools
This MCP server provides 6 generic tools that can access any Bitbucket API endpoint:
Tool
Description
Parameters
bb_get
GET any Bitbucket API endpoint (read data)
path, queryParams?, jq?, outputFormat?
bb_post
POST to any endpoint (create resources)
path, body, queryParams?, jq?, outputFormat?
bb_put
PUT to any endpoint (replace resources)
path, body, queryParams?, jq?, outputFormat?
bb_patch
PATCH any endpoint (partial updates)
path, body, queryParams?, jq?, outputFormat?
bb_delete
DELETE any endpoint (remove resources)
path, queryParams?, jq?, outputFormat?
bb_clone
Clone a repository locally
workspaceSlug?, repoSlug, targetPath
Tool Parameters
All API tools support these common parameters:
path (required): API endpoint path starting with / (the /2.0 prefix is added automatically)
What is TOON? Token-Oriented Object Notation is a format optimized for LLMs that reduces token consumption by 30-60% compared to JSON. It uses tabular arrays and minimal syntax while preserving all data.
Default behavior: All tools return TOON format by default. You can override this with outputFormat: "json" if needed.
All tools support optional JMESPath (jq) filtering to extract specific data and reduce token costs further:
Important: Always use jq to filter responses! Unfiltered API responses can be very large and expensive in terms of tokens.
# Get just repository names
npx -y @aashari/mcp-server-atlassian-bitbucket get \
--path "/repositories/myworkspace" \
--jq "values[].name"
# Get PR titles and states (custom object shape)
npx -y @aashari/mcp-server-atlassian-bitbucket get \
--path "/repositories/myworkspace/myrepo/pullrequests" \
--jq "values[].{title: title, state: state, author: author.display_name}"
# Get first result only
npx -y @aashari/mcp-server-atlassian-bitbucket get \
--path "/repositories/myworkspace" \
--jq "values[0]"
# Explore schema with one item first, then filter
npx -y @aashari/mcp-server-atlassian-bitbucket get \
--path "/workspaces" \
--query-params '{"pagelen": "1"}'
Common JMESPath patterns:
values[*].fieldName - Extract single field from all items
--workspace-slug <slug> (optional) - Workspace slug (uses default if not provided)
--repo-slug <slug> (required) - Repository slug
--target-path <path> (required) - Absolute path to parent directory where repo will be cloned
Debugging
Enable Debug Mode
Set the DEBUG environment variable to see detailed logging:
# For CLI testing
DEBUG=true npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"
# For Claude Desktop - add to config
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
"env": {
"DEBUG": "true",
"ATLASSIAN_USER_EMAIL": "...",
"ATLASSIAN_API_TOKEN": "..."
}
}
}
}
Log files: When running in MCP mode, logs are written to ~/.mcp/data/@aashari-mcp-server-atlassian-bitbucket.[session-id].log
Test with HTTP Mode
For interactive debugging, run the server in HTTP mode and use the MCP Inspector:
# Set credentials first
export ATLASSIAN_USER_EMAIL="[email protected]"
export ATLASSIAN_API_TOKEN="your_token"
export DEBUG=true
# Start HTTP server with MCP Inspector
npx -y @aashari/mcp-server-atlassian-bitbucket
# Then in another terminal:
PORT=3000 npm run mcp:inspect
This opens a visual interface to test tools and see request/response data.
Common Issues
Server not appearing in Claude Desktop:
Check config file syntax (valid JSON)
Restart Claude Desktop completely
Check Claude Desktop logs: ~/Library/Logs/Claude/mcp*.log (macOS)
Tools not working:
Enable DEBUG mode to see detailed errors
Test with CLI first to isolate MCP vs credentials issues
Verify API paths are correct (case-sensitive)
Troubleshooting
"Authentication failed" or "403 Forbidden"
Choose the right authentication method:
Standard Atlassian method (recommended): Use your Atlassian account email + API token (works with any Atlassian service)
Bitbucket-specific method (legacy): Use your Bitbucket username + App password (Bitbucket only)
Node.js/TypeScript MCP server for Atlassian Bitbucket. Enables AI systems (LLMs) to interact with workspaces, repositories, and pull requests via tools (list, get, comment, search). Connects AI direct
Node.js/TypeScript MCP server for Atlassian Bitbucket. Enables AI systems (LLMs) to interact with workspaces, repositories, and pull requests via tools (list, get, comment, search). Connects AI directly to version control workflows through the standard MC
@aashari/mcp Server Atlassian Bitbucket 需要 API 金鑰嗎?
這筆記錄未列出必要的環境變數。
@aashari/mcp Server Atlassian Bitbucket 使用哪種傳輸方式?
@aashari/mcp Server Atlassian Bitbucket 透過 stdio 在本機執行。
@aashari/mcp Server Atlassian Bitbucket 上次檢查是什麼時候?
上次檢查時間:2026-11-17。 Node.js/TypeScript MCP server for Atlassian Bitbucket. Enables AI systems (LLMs) to interact with workspaces, repositories, and pull requests via tools (list, get, comment, search). Connects AI directly to version control workflows through the standard MC