Bitbucket MCP Server

add_comment

Add general, inline, threaded, or task comments to Bitbucket pull requests, including code suggestions and automatic line lookup from diff snippets.

Instructions

Add a PR comment: general, threaded reply (parent_comment_id), inline (file_path + line_number), code suggestion (suggestion), or task (severity BLOCKER, Server only). code_snippet auto-resolves line_number from exact diff text when line_number is unknown.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "workspace": "<workspace>",
      "repository": "<repository>",
      "pull_request_id": "<pull_request_id>",
      "comment_text": "<comment_text>"
    },
    "name": "add_comment"
  }
}

Input Schema

Name	Required	Description
`severity`	No	BLOCKER creates a task (Server only)
`file_path`	No	Inline comment file
`line_type`	No	Default CONTEXT
`workspace`	Yes	Project key (e.g., PROJ)
`repository`	Yes	Repository slug
`suggestion`	No	Replacement code block; needs file_path + line_number
`attachments`	No	Local files to upload & embed (Server/DC only). Item: path string or {file_path, alt_text?, render?: image\|link\|auto}
`line_number`	No	Inline comment line (or use code_snippet)
`code_snippet`	No	Exact diff line text to locate (whitespace-sensitive)
`comment_text`	Yes
`match_strategy`	No	On multiple snippet matches (default strict)
`search_context`	No	Disambiguates repeated code_snippet
`pull_request_id`	Yes	Pull request ID
`parent_comment_id`	No	Reply to this comment
`suggestion_end_line`	No	Multi-line suggestion end

Schema Changelog

Changes observed during successful MCP inspections.

Changed16 schema fields changedv3.0.1Sep 27, 2026

addedInput schema / properties / attachments

Added value: +{
+  "description": "Local files to upload & embed (Server/DC only). Item: path string or {file_path, alt_text?, render?: image|link|auto}",
+  "items": {
+    "oneOf": [
+      {
+        "type": "string"
+      },
+      {
+        "properties": {
+          "alt_text": {
+            "type": "string"
+          },
+          "file_path": {
+            "type": "string"
+          },
+          "render": {
+            "enum": [
+              "image",
+              "link",
+              "auto"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "file_path"
+        ],
+        "type": "object"
+      }
+    ]
+  },
+  "type": "array"
+}

changedInput schema / properties / code_snippet / description

Previous value: -"Exact code text from the diff to find and comment on. Use this instead of line_number for auto-detection. Must match exactly including whitespace (optional)"New value: +"Exact diff line text to locate (whitespace-sensitive)"

removedInput schema / properties / comment_text / description

Removed value: -"The main comment text. For suggestions, this is the explanation before the code suggestion."

changedInput schema / properties / file_path / description

Previous value: -"File path for inline comment. Required for inline comments. Example: \"src/components/Button.js\" (optional)"New value: +"Inline comment file"

changedInput schema / properties / line_number / description

Previous value: -"Exact line number in the file. Use this OR code_snippet, not both. Required with file_path unless using code_snippet (optional)"New value: +"Inline comment line (or use code_snippet)"

changedInput schema / properties / line_type / description

Previous value: -"Type of line: ADDED (green/new lines), REMOVED (red/deleted lines), or CONTEXT (unchanged lines). Default: CONTEXT"New value: +"Default CONTEXT"

changedInput schema / properties / match_strategy / description

Previous value: -"How to handle multiple matches when using code_snippet. \"strict\": fail with detailed error showing all matches. \"best\": automatically pick the highest confidence match. Default: \"strict\""New value: +"On multiple snippet matches (default strict)"

changedInput schema / properties / parent_comment_id / description

Previous value: -"ID of comment to reply to. Use this to create threaded conversations (optional)"New value: +"Reply to this comment"

changedInput schema / properties / repository / description

Previous value: -"Repository slug (e.g., \"my-repo\")"New value: +"Repository slug"

changedInput schema / properties / search_context / description

Previous value: -"Additional context lines to help locate the exact position when using code_snippet. Useful when the same code appears multiple times (optional)"New value: +"Disambiguates repeated code_snippet"

removedInput schema / properties / search_context / properties / after / description

Removed value: -"Array of code lines that appear AFTER the target line. Helps disambiguate when code_snippet appears multiple times"

removedInput schema / properties / search_context / properties / before / description

Removed value: -"Array of code lines that appear BEFORE the target line. Helps disambiguate when code_snippet appears multiple times"

addedInput schema / properties / severity

Added value: +{
+  "description": "BLOCKER creates a task (Server only)",
+  "enum": [
+    "NORMAL",
+    "BLOCKER"
+  ],
+  "type": "string"
+}

changedInput schema / properties / suggestion / description

Previous value: -"Replacement code for a suggestion. Creates a suggestion block that can be applied in Bitbucket UI. Requires file_path and line_number. For multi-line, include newlines in the string (optional)"New value: +"Replacement code block; needs file_path + line_number"

changedInput schema / properties / suggestion_end_line / description

Previous value: -"For multi-line suggestions: the last line number to replace. If not provided, only replaces the single line at line_number (optional)"New value: +"Multi-line suggestion end"

changedInput schema / properties / workspace / description

Previous value: -"Bitbucket workspace/project key (e.g., \"PROJ\")"New value: +"Project key (e.g., PROJ)"

First observedv1.0.0Aug 15, 2025

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly=false, idempotent=false, destructive=false, and the description is consistent with a write operation. It adds meaningful operational detail beyond the annotations: Server-only gating for task/attachments, whitespace-sensitivity of code_snippet, and the strict/best match fallback, though it doesn't warn that repeated calls create duplicate comments.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence that front-loads the modes and puts the code_snippet fallback last. It is dense but every clause carries signal; the only slight cost is that the parenthetical detail makes it feel packed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter mutation with nested objects and no output schema, the description covers the mode-selection logic and the trickiest parameter interaction (snippet-to-line resolution). Remaining detail like attachments is well handled by the 93% schema coverage, so nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 93%, so the baseline is 3, but the description genuinely adds semantics: severity BLOCKER creates a task, suggestion requires file_path + line_number, and code_snippet auto-resolves line_number from exact diff text. These are cross-parameter relationships the schema alone doesn't make explicit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Add) and resource (PR comment) and then enumerates the five distinct comment modes it supports, so an agent can immediately tell this is the creation tool versus the sibling manage_comment.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The mode list effectively explains when to use each variant (general vs threaded reply vs inline vs suggestion vs task) and when to prefer code_snippet over line_number. It stops short of explicitly saying to use manage_comment for editing/deleting an existing comment, which would have fully closed the loop.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.