Skip to content
Back to search

mcp-server-atlassian-bitbucket

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 MCP interface.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aashari--mcp-server-atlassian-bitbucket/badge.svg)](/listings/aashari--mcp-server-atlassian-bitbucket)

HTML

<a href="/listings/aashari--mcp-server-atlassian-bitbucket"><img src="/api/listings/aashari--mcp-server-atlassian-bitbucket/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Get up and running in 2 minutes:

1. Get Your Bitbucket Credentials

> **IMPORTANT**: Bitbucket App Passwords are being deprecated and will be removed by **June 2026**. We recommend using **Scoped API Tokens** for new setups.

Option A: Scoped API Token (Recommended - Future-Proof)

**Bitbucket is deprecating app passwords**. Use the new scoped API tokens instead:

1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens) 2. Click **"Create API token with scopes"** 3. Select **"Bitbucket"** as the product 4. Choose the appropriate scopes: - **For read-only access**: `repository`, `workspace` - **For full functionality**: `repository`, `workspace`, `pullrequest` 5. Copy the generated token (starts with `ATATT`) 6. Use with your Atlassian email as the username

Option B: App Password (Legacy - Will be deprecated)

Generate a Bitbucket App Password (legacy method): 1. Go to [Bitbucket App Passwords](https://bitbucket.org/account/settings/app-passwords/) 2. Click "Create app password" 3. Give it a name like "AI Assistant" 4. Select these permissions: - **Workspaces**: Read - **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="your.email@company.com"
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}"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 659 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Connect AI to Your Bitbucket Repositories
  2. 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.
  3. [![NPM Version](https://img.shields.io/npm/v/@aashari/mcp-server-atlassian-bitbucket)](https://www.npmjs.com/package/@aashari/mcp-server-atlassian-bitbucket)
  4. [![License](https://img.shields.io/npm/l/@aashari/mcp-server-atlassian-bitbucket)](https://github.com/aashari/mcp-server-atlassian-bitbucket/blob/main/LICENSE)
  5. ## What You Can Do
  6. - **Ask AI about your code**: "What's the latest commit in my main repository?"
  7. - **Get PR insights**: "Show me all open pull requests that need review"
  8. - **Search your codebase**: "Find all JavaScript files that use the authentication function"
  9. - **Review code changes**: "Compare the differences between my feature branch and main"
  10. - **Manage pull requests**: "Create a PR for my new-feature branch"
  11. - **Automate workflows**: "Add a comment to PR #123 with the test results"
  12. ## Perfect For
  13. - **Developers** who want AI assistance with code reviews and repository management
  14. - **Team Leads** needing quick insights into project status and pull request activity
  15. - **DevOps Engineers** automating repository workflows and branch management
  16. - **Anyone** who wants to interact with Bitbucket using natural language
  17. ## Requirements
  18. - **Node.js** 18.0.0 or higher
  19. - **Bitbucket Cloud** account (not Bitbucket Server/Data Center)
  20. - **Authentication credentials**: Scoped API Token (recommended) or App Password (legacy)
  21. ## Quick Start
  22. Get up and running in 2 minutes:
  23. ### 1. Get Your Bitbucket Credentials
  24. > **IMPORTANT**: Bitbucket App Passwords are being deprecated and will be removed by **June 2026**. We recommend using **Scoped API Tokens** for new setups.
  25. #### Option A: Scoped API Token (Recommended - Future-Proof)
  26. **Bitbucket is deprecating app passwords**. Use the new scoped API tokens instead:
  27. 1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
  28. 2. Click **"Create API token with scopes"**
  29. 3. Select **"Bitbucket"** as the product
  30. 4. Choose the appropriate scopes:
  31. - **For read-only access**: `repository`, `workspace`
  32. - **For full functionality**: `repository`, `workspace`, `pullrequest`
  33. 5. Copy the generated token (starts with `ATATT`)
  34. 6. Use with your Atlassian email as the username
  35. #### Option B: App Password (Legacy - Will be deprecated)
  36. Generate a Bitbucket App Password (legacy method):
  37. 1. Go to [Bitbucket App Passwords](https://bitbucket.org/account/settings/app-passwords/)
  38. 2. Click "Create app password"
  39. 3. Give it a name like "AI Assistant"
  40. 4. Select these permissions:
  41. - **Workspaces**: Read
  42. - **Repositories**: Read (and Write if you want AI to create PRs/comments)
  43. - **Pull Requests**: Read (and Write for PR management)
  44. ### 2. Try It Instantly
  45. ```bash
  46. # Set your credentials (choose one method)
  47. # Method 1: Scoped API Token (recommended - future-proof)
  48. export ATLASSIAN_USER_EMAIL="your.email@company.com"
  49. export ATLASSIAN_API_TOKEN="your_scoped_api_token" # Token starting with ATATT
  50. # OR Method 2: Legacy App Password (will be deprecated June 2026)
  51. export ATLASSIAN_BITBUCKET_USERNAME="your_username"
  52. export ATLASSIAN_BITBUCKET_APP_PASSWORD="your_app_password"
  53. # List your workspaces
  54. npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"
  55. # List repositories in a workspace
  56. npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace"
  57. # Get pull requests for a repository
  58. npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace/your-repo/pullrequests"
  59. # Get repository details with JMESPath filtering
  60. npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace/your-repo" --jq "{name: name, language: language}"
  61. ```
  62. ## Connect to AI Assistants
  63. ### For Claude Desktop Users
  64. Add this to your Claude configuration file (`~/.claude/claude_desktop_config.json`):
  65. **Option 1: Scoped API Token (recommended - future-proof)**
  66. ```json
  67. {
  68. "mcpServers": {
  69. "bitbucket": {
  70. "command": "npx",
  71. "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
  72. "env": {
  73. "ATLASSIAN_USER_EMAIL": "your.email@company.com",
  74. "ATLASSIAN_API_TOKEN": "your_scoped_api_token"
  75. }
  76. }
  77. }
  78. }
  79. ```
  80. **Option 2: Legacy App Password (will be deprecated June 2026)**
  81. ```json
  82. {
  83. "mcpServers": {
  84. "bitbucket": {
  85. "command": "npx",
  86. "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
  87. "env": {
  88. "ATLASSIAN_BITBUCKET_USERNAME": "your_username",
  89. "ATLASSIAN_BITBUCKET_APP_PASSWORD": "your_app_password"
  90. }
  91. }
  92. }
  93. }
  94. ```
  95. Restart Claude Desktop, and you'll see the bitbucket server in the status bar.
  96. ### For Other AI Assistants
  97. Most AI assistants support MCP. You can either:
  98. **Option 1: Use npx (recommended - always latest version):**
  99. Configure your AI assistant to run: `npx -y @aashari/mcp-server-atlassian-bitbucket`
  100. **Option 2: Install globally:**
  101. ```bash
  102. npm install -g @aashari/mcp-server-atlassian-bitbucket
  103. ```
  104. Then configure your AI assistant to use the MCP server with STDIO transport.
  105. **Supported AI assistants:**
  106. - Claude Desktop (official support)
  107. - Cursor AI
  108. - Continue.dev
  109. - Cline
  110. - Any MCP-compatible client
  111. ### Alternative: Configuration File
  112. Create `~/.mcp/configs.json` for system-wide configuration:
  113. **Option 1: Scoped API Token (recommended - future-proof)**
  114. ```json
  115. {
  116. "bitbucket": {
  117. "environments": {
  118. "ATLASSIAN_USER_EMAIL": "your.email@company.com",
  119. "ATLASSIAN_API_TOKEN": "your_scoped_api_token",
  120. "BITBUCKET_DEFAULT_WORKSPACE": "your_main_workspace"
  121. }
  122. }
  123. }
  124. ```
  125. **Option 2: Legacy App Password (will be deprecated June 2026)**
  126. ```json
  127. {
  128. "bitbucket": {
  129. "environments": {
  130. "ATLASSIAN_BITBUCKET_USERNAME": "your_username",
  131. "ATLASSIAN_BITBUCKET_APP_PASSWORD": "your_app_password",
  132. "BITBUCKET_DEFAULT_WORKSPACE": "your_main_workspace"
  133. }
  134. }
  135. }
  136. ```
  137. **Alternative config keys:** The system also accepts `"atlassian-bitbucket"`, `"@aashari/mcp-server-atlassian-bitbucket"`, or `"mcp-server-atlassian-bitbucket"` instead of `"bitbucket"`.
  138. ## Available Tools
  139. This MCP server provides 6 generic tools that can access any Bitbucket API endpoint:
  140. | Tool | Description | Parameters |
  141. |------|-------------|------------|
  142. | `bb_get` | GET any Bitbucket API endpoint (read data) | `path`, `queryParams?`, `jq?`, `outputFormat?` |
  143. | `bb_post` | POST to any endpoint (create resources) | `path`, `body`, `queryParams?`, `jq?`, `outputFormat?` |
  144. | `bb_put` | PUT to any endpoint (replace resources) | `path`, `body`, `queryParams?`, `jq?`, `outputFormat?` |
  145. | `bb_patch` | PATCH any endpoint (partial updates) | `path`, `body`, `queryParams?`, `jq?`, `outputFormat?` |
  146. | `bb_delete` | DELETE any endpoint (remove resources) | `path`, `queryParams?`, `jq?`, `outputFormat?` |
  147. | `bb_clone` | Clone a repository locally | `workspaceSlug?`, `repoSlug`, `targetPath` |
  148. ### Tool Parameters
  149. All API tools support these common parameters:
  150. - **`path`** (required): API endpoint path starting with `/` (the `/2.0` prefix is added automatically)
  151. - **`queryParams`** (optional): Key-value pairs for query parameters (e.g., `{"pagelen": "25", "page": "2"}`)
  152. - **`jq`** (optional): JMESPath expression to filter/transform the response - **highly recommended** to reduce token costs
  153. - **`outputFormat`** (optional): `"toon"` (default, 30-60% fewer tokens) or `"json"`
  154. - **`body`** (required for POST/PUT/PATCH): Request body as JSON object
  155. ### Common API Paths
  156. All paths automatically have `/2.0` prepended. Full Bitbucket Cloud REST API 2.0 reference: https://developer.atlassian.com/cloud/bitbucket/rest/
  157. **Workspaces & Repositories:**
  158. - `/workspaces` - List all workspaces
  159. - `/repositories/{workspace}` - List repos in workspace
  160. - `/repositories/{workspace}/{repo}` - Get repo details
  161. - `/repositories/{workspace}/{repo}/refs/branches` - List branches
  162. - `/repositories/{workspace}/{repo}/refs/branches/{branch_name}` - Get/delete branch
  163. - `/repositories/{workspace}/{repo}/commits` - List commits
  164. - `/repositories/{workspace}/{repo}/commits/{commit}` - Get commit details
  165. - `/repositories/{workspace}/{repo}/src/{commit}/{filepath}` - Get file content
  166. **Pull Requests:**
  167. - `/repositories/{workspace}/{repo}/pullrequests` - List PRs (GET) or create PR (POST)
  168. - `/repositories/{workspace}/{repo}/pullrequests/{id}` - Get/update/delete PR
  169. - `/repositories/{workspace}/{repo}/pullrequests/{id}/diff` - Get PR diff
  170. - `/repositories/{workspace}/{repo}/pullrequests/{id}/comments` - List/add PR comments
  171. - `/repositories/{workspace}/{repo}/pullrequests/{id}/approve` - Approve PR (POST) or remove approval (DELETE)
  172. - `/repositories/{workspace}/{repo}/pullrequests/{id}/request-changes` - Request changes (POST)
  173. - `/repositories/{workspace}/{repo}/pullrequests/{id}/merge` - Merge PR (POST)
  174. - `/repositories/{workspace}/{repo}/pullrequests/{id}/decline` - Decline PR (POST)
  175. **Comparisons:**
  176. - `/repositories/{workspace}/{repo}/diff/{source}..{destination}` - Compare branches/commits
  177. **Other Resources:**
  178. - `/repositories/{workspace}/{repo}/issues` - List/manage issues
  179. - `/repositories/{workspace}/{repo}/downloads` - List/manage downloads
  180. - `/repositories/{workspace}/{repo}/pipelines` - Access Bitbucket Pipelines
  181. - `/repositories/{workspace}/{repo}/deployments` - View deployments
  182. ### TOON Output Format
  183. **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.
  184. **Default behavior:** All tools return TOON format by default. You can override this with `outputFormat: "json"` if needed.
  185. **Example comparison:**
  186. ```
  187. JSON (verbose):
  188. {
  189. "values": [
  190. {"name": "repo1", "slug": "repo-1"},
  191. {"name": "repo2", "slug": "repo-2"}
  192. ]
  193. }
  194. TOON (efficient):
  195. values:
  196. name | slug
  197. repo1 | repo-1
  198. repo2 | repo-2
  199. ```
  200. Learn more: https://github.com/toon-format/toon
  201. ### JMESPath Filtering
  202. All tools support optional JMESPath (`jq`) filtering to extract specific data and reduce token costs further:
  203. **Important:** Always use `jq` to filter responses! Unfiltered API responses can be very large and expensive in terms of tokens.
  204. ```bash
  205. # Get just repository names
  206. npx -y @aashari/mcp-server-atlassian-bitbucket get \
  207. --path "/repositories/myworkspace" \
  208. --jq "values[].name"
  209. # Get PR titles and states (custom object shape)
  210. npx -y @aashari/mcp-server-atlassian-bitbucket get \
  211. --path "/repositories/myworkspace/myrepo/pullrequests" \
  212. --jq "values[].{title: title, state: state, author: author.display_name}"
  213. # Get first result only
  214. npx -y @aashari/mcp-server-atlassian-bitbucket get \
  215. --path "/repositories/myworkspace" \
  216. --jq "values[0]"
  217. # Explore schema with one item first, then filter
  218. npx -y @aashari/mcp-server-atlassian-bitbucket get \
  219. --path "/workspaces" \
  220. --query-params '{"pagelen": "1"}'
  221. ```
  222. **Common JMESPath patterns:**
  223. - `values[*].fieldName` - Extract single field from all items
  224. - `values[*].{key1: field1, key2: field2}` - Create custom object shape
  225. - `values[0]` - Get first item only
  226. - `values[:5]` - Get first 5 items
  227. - `values[?state=='OPEN']` - Filter by condition
  228. Full JMESPath reference: https://jmespath.org
  229. ## Real-World Examples
  230. ### Explore Your Repositories
  231. Ask your AI assistant:
  232. - *"List all repositories in my main workspace"*
  233. - *"Show me details about the backend-api repository"*
  234. - *"What's the commit history for the feature-auth branch?"*
  235. - *"Get the content of src/config.js from the main branch"*
  236. ### Manage Pull Requests
  237. Ask your AI assistant:
  238. - *"Show me all open pull requests that need review"*
  239. - *"Get details about pull request #42 including the code changes"*
  240. - *"Create a pull request from feature-login to main branch"*
  241. - *"Add a comment to PR #15 saying the tests passed"*
  242. - *"Approve pull request #33"*
  243. ### Work with Branches and Code
  244. Ask your AI assistant:
  245. - *"Compare my feature branch with the main branch"*
  246. - *"List all branches in the user-service repository"*
  247. - *"Show me the differences between commits abc123 and def456"*
  248. ## Advanced Usage
  249. ### Cost Optimization Tips
  250. 1. **Always use JMESPath filtering** - Extract only needed fields to minimize token usage
  251. 2. **Use pagination wisely** - Set `pagelen` query parameter to limit results (e.g., `{"pagelen": "10"}`)
  252. 3. **Explore schema first** - Fetch one item without filters to see available fields, then filter subsequent calls
  253. 4. **Leverage TOON format** - Default TOON format saves 30-60% tokens vs JSON
  254. 5. **Query parameters for filtering** - Use Bitbucket's `q` parameter for server-side filtering before results are returned
  255. ### Query Parameter Examples
  256. ```bash
  257. # Filter PRs by state
  258. npx -y @aashari/mcp-server-atlassian-bitbucket get \
  259. --path "/repositories/workspace/repo/pullrequests" \
  260. --query-params '{"state": "OPEN", "pagelen": "5"}' \
  261. --jq "values[*].{id: id, title: title}"
  262. # Search PRs by title
  263. npx -y @aashari/mcp-server-atlassian-bitbucket get \
  264. --path "/repositories/workspace/repo/pullrequests" \
  265. --query-params '{"q": "title~\"bug\""}' \
  266. --jq "values[*].{id: id, title: title}"
  267. # Filter repositories by role
  268. npx -y @aashari/mcp-server-atlassian-bitbucket get \
  269. --path "/repositories/workspace" \
  270. --query-params '{"role": "owner", "pagelen": "10"}'
  271. # Sort by updated date
  272. npx -y @aashari/mcp-server-atlassian-bitbucket get \
  273. --path "/repositories/workspace/repo/pullrequests" \
  274. --query-params '{"sort": "-updated_on"}' \
  275. --jq "values[*].{id: id, title: title, updated: updated_on}"
  276. ```
  277. ### Working with Large Responses
  278. When dealing with APIs that return large payloads:
  279. 1. **Use sparse fieldsets** - Add `fields` query parameter: `{"fields": "values.name,values.slug"}`
  280. 2. **Paginate results** - Use `pagelen` and `page` parameters
  281. 3. **Filter at the source** - Use Bitbucket's `q` parameter for server-side filtering
  282. 4. **Post-process with JQ** - Further filter the response with JMESPath
  283. Example combining all techniques:
  284. ```bash
  285. npx -y @aashari/mcp-server-atlassian-bitbucket get \
  286. --path "/repositories/workspace/repo/pullrequests" \
  287. --query-params '{"state": "OPEN", "pagelen": "10", "fields": "values.id,values.title,values.state"}' \
  288. --jq "values[*].{id: id, title: title}"
  289. ```
  290. ### Best Practices for AI Interactions
  291. 1. **Be specific with paths** - Use exact workspace/repo slugs (case-sensitive)
  292. 2. **Test with CLI first** - Verify paths and authentication before using in AI context
  293. 3. **Use descriptive JQ filters** - Extract meaningful field names for better AI understanding
  294. 4. **Enable DEBUG for troubleshooting** - See exactly what's being sent to Bitbucket API
  295. 5. **Check API limits** - Bitbucket Cloud has rate limits; use filtering to reduce calls
  296. ## CLI Commands
  297. The CLI mirrors the MCP tools for direct terminal access. All commands return JSON output (not TOON - TOON is only for MCP mode).
  298. ### Available Commands
  299. ```bash
  300. # Get help
  301. npx -y @aashari/mcp-server-atlassian-bitbucket --help
  302. # GET request
  303. npx -y @aashari/mcp-server-atlassian-bitbucket get \
  304. --path "/workspaces" \
  305. --jq "values[*].{name: name, slug: slug}"
  306. # GET with query parameters
  307. npx -y @aashari/mcp-server-atlassian-bitbucket get \
  308. --path "/repositories/myworkspace/myrepo/pullrequests" \
  309. --query-params '{"state": "OPEN", "pagelen": "10"}' \
  310. --jq "values[*].{id: id, title: title}"
  311. # POST request (create a PR)
  312. npx -y @aashari/mcp-server-atlassian-bitbucket post \
  313. --path "/repositories/myworkspace/myrepo/pullrequests" \
  314. --body '{"title": "My PR", "source": {"branch": {"name": "feature"}}, "destination": {"branch": {"name": "main"}}}' \
  315. --jq "{id: id, title: title}"
  316. # POST with query parameters
  317. npx -y @aashari/mcp-server-atlassian-bitbucket post \
  318. --path "/repositories/myworkspace/myrepo/pullrequests/42/comments" \
  319. --body '{"content": {"raw": "Looks good!"}}' \
  320. --query-params '{"fields": "id,content"}' \
  321. --jq "{id: id, content: content.raw}"
  322. # PUT request (replace resource)
  323. npx -y @aashari/mcp-server-atlassian-bitbucket put \
  324. --path "/repositories/myworkspace/myrepo" \
  325. --body '{"description": "Updated description", "is_private": true}'
  326. # PATCH request (partial update)
  327. npx -y @aashari/mcp-server-atlassian-bitbucket patch \
  328. --path "/repositories/myworkspace/myrepo/pullrequests/123" \
  329. --body '{"title": "Updated PR title"}'
  330. # DELETE request
  331. npx -y @aashari/mcp-server-atlassian-bitbucket delete \
  332. --path "/repositories/myworkspace/myrepo/refs/branches/old-branch"
  333. # Clone repository
  334. npx -y @aashari/mcp-server-atlassian-bitbucket clone \
  335. --workspace-slug myworkspace \
  336. --repo-slug myrepo \
  337. --target-path /absolute/path/to/parent/directory
  338. ```
  339. ### CLI Options
  340. **For `get` and `delete` commands:**
  341. - `-p, --path <path>` (required) - API endpoint path
  342. - `-q, --query-params <json>` (optional) - Query parameters as JSON string
  343. - `--jq <expression>` (optional) - JMESPath filter expression
  344. **For `post`, `put`, and `patch` commands:**
  345. - `-p, --path <path>` (required) - API endpoint path
  346. - `-b, --body <json>` (required) - Request body as JSON string
  347. - `-q, --query-params <json>` (optional) - Query parameters as JSON string
  348. - `--jq <expression>` (optional) - JMESPath filter expression
  349. **For `clone` command:**
  350. - `--workspace-slug <slug>` (optional) - Workspace slug (uses default if not provided)
  351. - `--repo-slug <slug>` (required) - Repository slug
  352. - `--target-path <path>` (required) - Absolute path to parent directory where repo will be cloned
  353. ## Debugging
  354. ### Enable Debug Mode
  355. Set the `DEBUG` environment variable to see detailed logging:
  356. ```bash
  357. # For CLI testing
  358. DEBUG=true npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"
  359. # For Claude Desktop - add to config
  360. {
  361. "mcpServers": {
  362. "bitbucket": {
  363. "command": "npx",
  364. "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
  365. "env": {
  366. "DEBUG": "true",
  367. "ATLASSIAN_USER_EMAIL": "...",
  368. "ATLASSIAN_API_TOKEN": "..."
  369. }
  370. }
  371. }
  372. }
  373. ```
  374. **Log files:** When running in MCP mode, logs are written to `~/.mcp/data/@aashari-mcp-server-atlassian-bitbucket.[session-id].log`
  375. ### Test with HTTP Mode
  376. For interactive debugging, run the server in HTTP mode and use the MCP Inspector:
  377. ```bash
  378. # Set credentials first
  379. export ATLASSIAN_USER_EMAIL="your.email@company.com"
  380. export ATLASSIAN_API_TOKEN="your_token"
  381. export DEBUG=true
  382. # Start HTTP server with MCP Inspector
  383. npx -y @aashari/mcp-server-atlassian-bitbucket
  384. # Then in another terminal:
  385. PORT=3000 npm run mcp:inspect
  386. ```
  387. This opens a visual interface to test tools and see request/response data.
  388. ### Common Issues
  389. **Server not appearing in Claude Desktop:**
  390. 1. Check config file syntax (valid JSON)
  391. 2. Restart Claude Desktop completely
  392. 3. Check Claude Desktop logs: `~/Library/Logs/Claude/mcp*.log` (macOS)
  393. **Tools not working:**
  394. 1. Enable DEBUG mode to see detailed errors
  395. 2. Test with CLI first to isolate MCP vs credentials issues
  396. 3. Verify API paths are correct (case-sensitive)
  397. ## Troubleshooting
  398. ### "Authentication failed" or "403 Forbidden"
  399. 1. **Choose the right authentication method**:
  400. - **Standard Atlassian method** (recommended): Use your Atlassian account email + API token (works with any Atlassian service)
  401. - **Bitbucket-specific method** (legacy): Use your Bitbucket username + App password (Bitbucket only)
  402. 2. **For Scoped API Tokens** (recommended):
  403. - Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
  404. - Make sure your token is still active and has the right scopes
  405. - Required scopes: `repository`, `workspace` (add `pullrequest` for PR management)
  406. - Token should start with `ATATT`
  407. 3. **For Bitbucket App Passwords** (legacy):
  408. - Go to [Bitbucket App Passwords](https://bitbucket.org/account/settings/app-passwords/)
  409. - Make sure your app password has the right permissions
  410. - Remember: App passwords will be deprecated by June 2026
  411. 4. **Verify your credentials**:
  412. ```bash
  413. # Test credentials with CLI
  414. export ATLASSIAN_USER_EMAIL="your.email@company.com"
  415. export ATLASSIAN_API_TOKEN="your_token"
  416. npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"
  417. ```
  418. 5. **Environment variable naming**:
  419. - Use `ATLASSIAN_USER_EMAIL` + `ATLASSIAN_API_TOKEN` for scoped tokens
  420. - Use `ATLASSIAN_BITBUCKET_USERNAME` + `ATLASSIAN_BITBUCKET_APP_PASSWORD` for app passwords
  421. - Don't use `ATLASSIAN_SITE_NAME` - it's not needed for Bitbucket Cloud
  422. ### "Resource not found" or "404"
  423. 1. **Check the API path**:
  424. - Paths are case-sensitive
  425. - Use workspace slug (from URL), not display name
  426. - Example: If your repo URL is `https://bitbucket.org/myteam/my-repo`, use `myteam` and `my-repo`
  427. 2. **Verify the resource exists**:
  428. ```bash
  429. # List workspaces to find the correct slug
  430. npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"
  431. ```
  432. ### Claude Desktop Integration Issues
  433. 1. **Restart Claude Desktop** after updating the config file
  434. 2. **Verify config file location**:
  435. - macOS: `~/.claude/claude_desktop_config.json`
  436. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  437. ### Getting Help
  438. If you're still having issues:
  439. 1. Run a simple test command to verify everything works
  440. 2. Check the [GitHub Issues](https://github.com/aashari/mcp-server-atlassian-bitbucket/issues) for similar problems
  441. 3. Create a new issue with your error message and setup details
  442. ## Frequently Asked Questions
  443. ### What permissions do I need?
  444. **For Scoped API Tokens** (recommended):
  445. - Required scopes: `repository`, `workspace`
  446. - Add `pullrequest` for PR management
  447. **For Bitbucket App Passwords** (legacy):
  448. - For **read-only access**: Workspaces: Read, Repositories: Read, Pull Requests: Read
  449. - For **full functionality**: Add "Write" permissions for Repositories and Pull Requests
  450. ### Can I use this with private repositories?
  451. Yes! This works with both public and private repositories. You just need the appropriate permissions through your credentials.
  452. ### What AI assistants does this work with?
  453. Any AI assistant that supports the Model Context Protocol (MCP):
  454. - Claude Desktop
  455. - Cursor AI
  456. - Continue.dev
  457. - Many others
  458. ### Is my data secure?
  459. Yes! This tool:
  460. - Runs entirely on your local machine
  461. - Uses your own Bitbucket credentials
  462. - Never sends your data to third parties
  463. - Only accesses what you give it permission to access
  464. ## Migration from v1.x
  465. Version 2.0 represents a major architectural change. If you're upgrading from v1.x:
  466. **Before (v1.x) - 20+ specific tools:**
  467. ```
  468. bb_ls_workspaces, bb_get_workspace, bb_ls_repos, bb_get_repo,
  469. bb_list_branches, bb_add_branch, bb_get_commit_history, bb_get_file,
  470. bb_ls_prs, bb_get_pr, bb_add_pr, bb_update_pr, bb_approve_pr, bb_reject_pr,
  471. bb_ls_pr_comments, bb_add_pr_comment, bb_diff_branches, bb_diff_commits, bb_search
  472. ```
  473. **After (v2.0+) - 6 generic tools:**
  474. ```
  475. bb_get, bb_post, bb_put, bb_patch, bb_delete, bb_clone
  476. ```
  477. ### Migration Examples
  478. | v1.x Tool | v2.0+ Equivalent |
  479. |-----------|------------------|
  480. | `bb_ls_workspaces()` | `bb_get(path: "/workspaces")` |
  481. | `bb_ls_repos(workspace: "myteam")` | `bb_get(path: "/repositories/myteam")` |
  482. | `bb_get_repo(workspace: "myteam", repo: "myrepo")` | `bb_get(path: "/repositories/myteam/myrepo")` |
  483. | `bb_list_branches(workspace: "myteam", repo: "myrepo")` | `bb_get(path: "/repositories/myteam/myrepo/refs/branches")` |
  484. | `bb_add_branch(...)` | `bb_post(path: "/repositories/.../refs/branches", body: {...})` |
  485. | `bb_ls_prs(workspace: "myteam", repo: "myrepo")` | `bb_get(path: "/repositories/myteam/myrepo/pullrequests")` |
  486. | `bb_get_pr(workspace: "myteam", repo: "myrepo", id: 42)` | `bb_get(path: "/repositories/myteam/myrepo/pullrequests/42")` |
  487. | `bb_add_pr(...)` | `bb_post(path: "/repositories/.../pullrequests", body: {...})` |
  488. | `bb_update_pr(...)` | `bb_patch(path: "/repositories/.../pullrequests/42", body: {...})` |
  489. | `bb_approve_pr(workspace: "myteam", repo: "myrepo", id: 42)` | `bb_post(path: "/repositories/myteam/myrepo/pullrequests/42/approve", body: {})` |
  490. | `bb_diff_branches(...)` | `bb_get(path: "/repositories/.../diff/branch1..branch2")` |
  491. ### Key Changes
  492. 1. **All tools now require explicit paths** - more verbose but more flexible
  493. 2. **Use JMESPath filtering** - extract only what you need to reduce tokens
  494. 3. **TOON format by default** - 30-60% fewer tokens (can override with `outputFormat: "json"`)
  495. 4. **Direct Bitbucket API access** - any API endpoint works, no code changes needed for new features
  496. ## Support
  497. Need help? Here's how to get assistance:
  498. 1. **Check the troubleshooting section above** - most common issues are covered there
  499. 2. **Visit our GitHub repository** for documentation and examples: [github.com/aashari/mcp-server-atlassian-bitbucket](https://github.com/aashari/mcp-server-atlassian-bitbucket)
  500. 3. **Report issues** at [GitHub Issues](https://github.com/aashari/mcp-server-atlassian-bitbucket/issues)
  501. 4. **Start a discussion** for feature requests or general questions
  502. ---
  503. *Made with care for developers who want to bring AI into their Bitbucket workflow.*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.