### Manual Installation of Bitbucket Server MCP

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Installs the Bitbucket Server MCP server by running the npm install command.

```bash
npm install
```

--------------------------------

### Install Bitbucket Server MCP via Smithery

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Installs the Bitbucket Server MCP server automatically using the Smithery CLI for Claude Desktop.

```bash
npx -y @smithery/cli install @garc33/bitbucket-server-mcp-server --client claude
```

--------------------------------

### Instantiate BitbucketServer with Environment Variables

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Configure the BitbucketServer instance using environment variables for URL, token, and default project. This is a common setup for standalone deployments.

```typescript
import { BitbucketServer } from './src/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

// Option 1: configure via environment variables
// BITBUCKET_URL, BITBUCKET_TOKEN (or USERNAME+PASSWORD), BITBUCKET_DEFAULT_PROJECT
const server = new BitbucketServer();
```

--------------------------------

### Connect BitbucketServer to Stdio Transport

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Connect the instantiated BitbucketServer to a stdio transport and start serving requests. This is typically done after instantiation.

```typescript
// Connect to stdio transport and start serving
const transport = new StdioServerTransport();
await server.connect(transport);
// OR: shorthand
await server.run(); // connects to stdio and logs startup
```

--------------------------------

### MCP Server JSON Configuration

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Complete wiring example for configuring an MCP server to connect to Bitbucket Server. Includes environment variables for authentication, project scope, and logging.

```json
{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/path/to/bitbucket-server/build/index.js"],
      "env": {
        "BITBUCKET_URL": "https://bitbucket.example.com",
        "BITBUCKET_TOKEN": "ATBB-my-personal-access-token",
        "BITBUCKET_DEFAULT_PROJECT": "MYPROJ",
        "BITBUCKET_DIFF_MAX_LINES_PER_FILE": "300",
        "BITBUCKET_READ_ONLY": "false",
        "BITBUCKET_CUSTOM_HEADERS": "X-Zero-Trust-Token=zt-abc123,X-Proxy-Auth=proxy-key",
        "BITBUCKET_LOG_PATH": "/var/log/bitbucket-mcp/server.log"
      }
    }
  }
}
```

--------------------------------

### MCP Tool Call: list_repositories

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Example of calling the `list_repositories` MCP tool to list repositories within a specific project or all accessible repositories if no project is specified. Returns slugs, clone URLs, and state.

```json
{
  "method": "tools/call",
  "params": {
    "name": "list_repositories",
    "arguments": { "project": "MYPROJ", "limit": 25 }
  }
}
```

```json
// Response:
{
  "project": "MYPROJ",
  "total": 2,
  "showing": 2,
  "repositories": [
    {
      "slug": "my-app",
      "name": "My App",
      "project": "MYPROJ",
      "public": false,
      "cloneUrl": "https://bitbucket.example.com/scm/myproj/my-app.git",
      "state": "AVAILABLE"
    }
  ]
}
```

--------------------------------

### MCP Tool Call: list_projects

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Example of calling the `list_projects` MCP tool to retrieve a list of all accessible Bitbucket projects. Use this to discover valid project keys for subsequent operations.

```json
// MCP tool call (JSON-RPC via stdio)
{
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": { "limit": 10, "start": 0 }
  }
}
```

```json
// Expected response content[0].text (pretty-printed JSON):
{
  "total": 3,
  "showing": 3,
  "projects": [
    { "key": "MYPROJ", "name": "My Project", "description": "Main codebase", "public": false, "type": "NORMAL" },
    { "key": "INFRA",  "name": "Infrastructure", "description": null, "public": false, "type": "NORMAL" }
  ]
}
```

--------------------------------

### Get File Content MCP Tool

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Reads the contents of a file from a repository with line-level pagination. Returns lines as a string array. Supports specifying start and limit for pagination.

```json
{
  "method": "tools/call",
  "params": {
    "name": "get_file_content",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "filePath": "src/auth/token.ts",
      "branch": "feature/oauth2-login",
      "start": 0,
      "limit": 50
    }
  }
}
```

--------------------------------

### Get Pull Request

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Retrieves full PR metadata: status, reviewers with their approval state, source/target refs, and all Bitbucket-managed fields.

```json
{
  "method": "tools/call",
  "params": {
    "name": "get_pull_request",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "prId": 42
    }
  }
}
```

--------------------------------

### Get Pull Request Details and Activity

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Commands to retrieve details, comments, and activity timeline for a specific pull request. Requires repository and PR ID.

```bash
# Get pull request details
get_pull_request --repository "my-repo" --prId 123
```

```bash
# Get only comments from a PR (no reviews/commits)
get_comments --project "MYPROJECT" --repository "my-repo" --prId 123
```

```bash
# Get full PR activity timeline
get_activities --repository "my-repo" --prId 123
```

--------------------------------

### Get All PR Activities

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Retrieve the complete activity timeline of a PR, including comments, reviews, commits, and rescopes, using the `get_activities` command. The response is paginated.

```json
{
  "method": "tools/call",
  "params": {
    "name": "get_activities",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "prId": 42
    }
  }
}
```

--------------------------------

### Get File Content

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Reads the contents of a file from a repository with line-level pagination. Returns lines as a string array.

```APIDOC
## MCP Tool: `get_file_content`

Reads the contents of a file from a repository with line-level pagination. Returns lines as a string array.

### Method
tools/call

### Parameters
#### Arguments
- **project** (string) - Required - The project key.
- **repository** (string) - Required - The repository slug.
- **filePath** (string) - Required - The path to the file.
- **branch** (string) - Optional - The branch name. Defaults to the repository's default branch.
- **start** (integer) - Optional - The starting line number for pagination. Defaults to 0.
- **limit** (integer) - Optional - The maximum number of lines to return. Defaults to 50.

### Request Example
```json
{
  "method": "tools/call",
  "params": {
    "name": "get_file_content",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "filePath": "src/auth/token.ts",
      "branch": "feature/oauth2-login",
      "start": 0,
      "limit": 50
    }
  }
}
```

### Response
#### Success Response
- **project** (string) - The project key.
- **repository** (string) - The repository slug.
- **filePath** (string) - The path to the file.
- **branch** (string) - The branch name.
- **isLastPage** (boolean) - Indicates if this is the last page of results.
- **size** (integer) - The total size of the file in bytes.
- **showing** (integer) - The number of lines returned in this response.
- **startLine** (integer) - The starting line number for this response.
- **lines** (array of strings) - An array containing the lines of the file.
```

--------------------------------

### Get Approved/Reviewed PR Activities

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Use `get_reviews` to fetch only APPROVED or REVIEWED activity entries from a PR's activity stream, providing a concise view of review decisions.

```json
{
  "method": "tools/call",
  "params": {
    "name": "get_reviews",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "prId": 42
    }
  }
}
```

--------------------------------

### Get Code Insights using MCP Tool

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Fetches Code Insights reports (e.g., SonarQube) and line-level annotations for a given pull request. Requires project, repository, and PR ID.

```json
{
  "method": "tools/call",
  "params": {
    "name": "get_code_insights",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "prId": 42
    }
  }
}
```

```json
{
  "reports": [
    { "key": "sonarqube", "title": "SonarQube", "result": "PASS", "data": [...] }
  ],
  "annotations": {
    "sonarqube": [
      { "path": "src/auth/token.ts", "line": 34, "severity": "MAJOR", "message": "Remove this hard-coded password." }
    ]
  }
}
```

--------------------------------

### Get Pull Request Diff

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Retrieves the unified diff for a PR as plain text. Supports configurable context lines and per-file line truncation to handle large changesets.

```json
{
  "method": "tools/call",
  "params": {
    "name": "get_diff",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "prId": 42,
      "contextLines": 5,
      "maxLinesPerFile": 200
    }
  }
}
```

--------------------------------

### Build and Run Bitbucket Server MCP from Source

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Instructions for building the Bitbucket Server MCP from source using npm, including running the standalone server and the interactive inspector.

```bash
npm install
npm run build
# Run standalone
npm start
# Inspect tools interactively
npm run inspector
```

--------------------------------

### BitbucketServer Constructor

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Instantiate the BitbucketServer class, configuring it via environment variables or explicit options. The constructor throws an error if `baseUrl` or credentials are not provided.

```APIDOC
## `BitbucketServer` constructor

Instantiate the server with environment variables or explicit options. Throws immediately if `baseUrl` or credentials are missing.

```typescript
import { BitbucketServer } from './src/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

// Option 1: configure via environment variables
// BITBUCKET_URL, BITBUCKET_TOKEN (or USERNAME+PASSWORD), BITBUCKET_DEFAULT_PROJECT
const server = new BitbucketServer();

// Option 2: configure programmatically (useful in tests / embedding)
const server = new BitbucketServer({
  baseUrl: 'https://bitbucket.example.com',
  token: 'ATBB-my-personal-access-token',
  defaultProject: 'MYPROJ',
  readOnly: false,
  maxLinesPerFile: 300,
  customHeaders: { 'X-Zero-Trust-Token': 'zt-abc123' },
});

// Connect to stdio transport and start serving
const transport = new StdioServerTransport();
await server.connect(transport);
// OR: shorthand
await server.run(); // connects to stdio and logs startup
```
```

--------------------------------

### List Projects and Repositories

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Commands to list accessible projects and repositories. Supports filtering by project key and pagination.

```bash
# List all accessible projects
list_projects
```

```bash
# List repositories in the default project (if BITBUCKET_DEFAULT_PROJECT is set)
list_repositories
```

```bash
# List repositories in a specific project
list_repositories --project "MYPROJECT"
```

```bash
# List projects with pagination
list_projects --limit 10 --start 0
```

--------------------------------

### Instantiate BitbucketServer Programmatically

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Configure the BitbucketServer instance with explicit options for base URL, token, default project, read-only mode, max lines per file, and custom headers. Useful for testing or embedding.

```typescript
const server = new BitbucketServer({
  baseUrl: 'https://bitbucket.example.com',
  token: 'ATBB-my-personal-access-token',
  defaultProject: 'MYPROJ',
  readOnly: false,
  maxLinesPerFile: 300,
  customHeaders: { 'X-Zero-Trust-Token': 'zt-abc123' },
});
```

--------------------------------

### MCP Server Configuration

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Sample VSCode MCP settings file for configuring the Bitbucket server integration. This includes command, arguments, and environment variables for authentication and connection.

```json
{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/path/to/bitbucket-server/build/index.js"],
      "env": {
        "BITBUCKET_URL": "https://your-bitbucket-server.com",
        "BITBUCKET_TOKEN": "your-access-token",
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_PASSWORD": "your-password",
        "BITBUCKET_DEFAULT_PROJECT": "your-default-project"
      }
    }
  }
}
```

--------------------------------

### list_projects

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Discover and explore Bitbucket projects. Lists all accessible projects with their details, essential for project discovery and finding the correct project keys to use in other operations.

```APIDOC
## list_projects

### Description
Lists all accessible Bitbucket projects with their details.

### Parameters
#### Query Parameters
- **limit** (number) - Optional - Number of projects to return (default: 25, max: 1000)
- **start** (number) - Optional - Start index for pagination (default: 0)
```

--------------------------------

### Get PR Comments

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Filter the PR activity stream to retrieve only COMMENTED entries using `get_comments`. This is useful for reading discussion threads without other activity types.

```json
{
  "method": "tools/call",
  "params": {
    "name": "get_comments",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "prId": 42
    }
  }
}
```

--------------------------------

### MCP Tool: list_projects

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Lists all Bitbucket projects accessible to the authenticated user. This tool returns project keys, names, descriptions, visibility, and type, and is useful for discovering valid project keys.

```APIDOC
## MCP Tool: `list_projects`

Lists all Bitbucket projects accessible to the authenticated user. Returns project keys, names, descriptions, visibility, and type. Use this as the first step to discover valid project keys.

```json
// MCP tool call (JSON-RPC via stdio)
{
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": { "limit": 10, "start": 0 }
  }
}

// Expected response content[0].text (pretty-printed JSON):
{
  "total": 3,
  "showing": 3,
  "projects": [
    { "key": "MYPROJ", "name": "My Project", "description": "Main codebase", "public": false, "type": "NORMAL" },
    { "key": "INFRA",  "name": "Infrastructure", "description": null, "public": false, "type": "NORMAL" }
  ]
}
```
```

--------------------------------

### List Branches

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Command to list all branches in a specified repository.

```bash
# List all branches in a repository
list_branches --repository "my-repo"
```

--------------------------------

### Browse Repository MCP Tool

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Lists files and directories at a given path within a repository, similar to 'ls'. Defaults to the repository root if path is omitted. Supports specifying path, branch, and limit.

```json
{
  "method": "tools/call",
  "params": {
    "name": "browse_repository",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "path": "src/auth",
      "branch": "main",
      "limit": 50
    }
  }
}
```

--------------------------------

### Browse Repository

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Lists files and directories at a given path within a repository, similar to `ls`. Defaults to the repository root.

```APIDOC
## MCP Tool: `browse_repository`

Lists files and directories at a given path within a repository, similar to `ls`. Defaults to the repository root.

### Method
tools/call

### Parameters
#### Arguments
- **project** (string) - Required - The project key.
- **repository** (string) - Required - The repository slug.
- **path** (string) - Optional - The path within the repository to list. Defaults to the root.
- **branch** (string) - Optional - The branch name. Defaults to the repository's default branch.
- **limit** (integer) - Optional - The maximum number of items to return. Defaults to 50.

### Request Example
```json
{
  "method": "tools/call",
  "params": {
    "name": "browse_repository",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "path": "src/auth",
      "branch": "main",
      "limit": 50
    }
  }
}
```

### Response
#### Success Response
- **project** (string) - The project key.
- **repository** (string) - The repository slug.
- **path** (string) - The path that was browsed.
- **branch** (string) - The branch that was browsed.
- **size** (integer) - The number of items listed.
- **items** (array) - An array of objects, each representing a file or directory with its name, type, and size.
```

--------------------------------

### Set Custom Log Path

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Configure a custom log file path by setting the BITBUCKET_LOG_PATH environment variable. The log directory will be created if it does not exist.

```json
{
  "env": {
    "BITBUCKET_LOG_PATH": "/var/log/bitbucket-mcp/server.log"
  }
}
```

--------------------------------

### browse_repository

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Explore the file and directory structure of a repository.

```APIDOC
## browse_repository

### Description
Browse files and directories in repositories to understand project organization and locate specific files.

### Parameters
- `project` (string) - Optional - Bitbucket project key (uses BITBUCKET_DEFAULT_PROJECT if not provided)
- `repository` (string) - Required - Repository slug
- `path` (string) - Optional - Directory path to browse (defaults to root)
- `branch` (string) - Optional - Branch or commit hash (defaults to main/master)
- `limit` (integer) - Optional - Maximum items to return (default: 50)
```

--------------------------------

### Build Bitbucket Server MCP

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Builds the Bitbucket Server MCP project using the npm run build command.

```bash
npm run build
```

--------------------------------

### Search and File Operations

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Commands for searching files and code, browsing repository structure, and reading file contents. Supports various search queries, path filtering, and line-based reading.

```bash
# Search for README files across all projects
search --query "README" --type "file" --limit 10
```

```bash
# Search for specific code patterns in a project
search --query "function getUserData" --type "code" --project "MYPROJECT"
```

```bash
# Search with file extension filter
search --query "config ext:yml" --project "MYPROJECT"
```

```bash
# Browse repository structure
browse_repository --project "MYPROJECT" --repository "my-repo"
```

```bash
# Browse specific directory
browse_repository --project "MYPROJECT" --repository "my-repo" --path "src/components"
```

```bash
# Read file contents
get_file_content --project "MYPROJECT" --repository "my-repo" --filePath "package.json" --limit 20
```

```bash
# Read specific lines from a large file
get_file_content --project "MYPROJECT" --repository "my-repo" --filePath "docs/CHANGELOG.md" --start 100 --limit 50
```

--------------------------------

### Create Pull Request

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Commands to create pull requests. Supports specifying project, repository, branches, title, and description. Uses default project if not specified.

```bash
# Create a pull request (using default project)
create_pull_request --repository "my-repo" --title "Feature: New functionality" --sourceBranch "feature/new-feature" --targetBranch "main"
```

```bash
# Create a pull request with specific project
create_pull_request --project "MYPROJECT" --repository "my-repo" --title "Bugfix: Critical issue" --sourceBranch "bugfix/critical" --targetBranch "develop" --description "Fixes critical issue #123"
```

--------------------------------

### Add Multiple Custom HTTP Headers

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Configure multiple custom HTTP headers by providing a comma-separated list of key-value pairs to the BITBUCKET_CUSTOM_HEADERS environment variable. Values can include equals signs.

```json
{
  "env": {
    "BITBUCKET_CUSTOM_HEADERS": "X-Custom-Header=value1,X-Proxy-Auth=token123"
  }
}
```

--------------------------------

### MCP Tool: list_repositories

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Lists repositories within a specified project or all accessible repositories if no project is provided. The tool returns repository slugs, clone URLs, and their current state.

```APIDOC
## MCP Tool: `list_repositories`

Lists repositories within a project (or all accessible repositories when no project is given). Returns slugs, clone URLs, and state.

```json
{
  "method": "tools/call",
  "params": {
    "name": "list_repositories",
    "arguments": { "project": "MYPROJ", "limit": 25 }
  }
}

// Response:
{
  "project": "MYPROJ",
  "total": 2,
  "showing": 2,
  "repositories": [
    {
      "slug": "my-app",
      "name": "My App",
      "project": "MYPROJ",
      "public": false,
      "cloneUrl": "https://bitbucket.example.com/scm/myproj/my-app.git",
      "state": "AVAILABLE"
    }
  ]
}
```
```

--------------------------------

### search

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Perform advanced code and file search across repositories using the Bitbucket search API.

```APIDOC
## search

### Description
Search across repositories using the Bitbucket search API with support for project/repository filtering and query optimization. Searches both file contents and filenames. Note: Search only works on the default branch of repositories.

### Parameters
- `query` (string) - Required - Search query string
- `project` (string) - Optional - Bitbucket project key to limit search scope
- `repository` (string) - Optional - Repository slug for repository-specific search
- `type` (string) - Optional - Query optimization - "file" (wraps query in quotes for exact filename matching) or "code" (default search behavior)
- `limit` (integer) - Optional - Number of results to return (default: 25, max: 100)
- `start` (integer) - Optional - Start index for pagination (default: 0)
```

--------------------------------

### list_repositories

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Browse and discover repositories within specific projects or across all accessible projects. Returns comprehensive repository information including clone URLs and metadata.

```APIDOC
## list_repositories

### Description
Explore repositories within specific projects or across all accessible projects.

### Parameters
#### Query Parameters
- **project** (string) - Optional - Bitbucket project key (uses BITBUCKET_DEFAULT_PROJECT if not provided)
- **limit** (number) - Optional - Number of repositories to return (default: 25, max: 1000)
- **start** (number) - Optional - Start index for pagination (default: 0)
```

--------------------------------

### Search Code and Files MCP Tool

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Searches code and filenames across repositories. Supports project/repository scoping and a 'file' type for exact filename matching. Specify 'code' or 'file' for the 'type' argument.

```json
{
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "getUserToken",
      "project": "MYPROJ",
      "repository": "my-app",
      "type": "code",
      "limit": 10
    }
  }
}
```

```json
{ "name": "search", "arguments": { "query": "README.md", "type": "file", "limit": 5 } }
```

--------------------------------

### Enable Read-Only Mode

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Set the BITBUCKET_READ_ONLY environment variable to 'true' to enable read-only mode. This restricts write operations, making it suitable for production or CI/CD environments.

```bash
export BITBUCKET_READ_ONLY=true
```

--------------------------------

### List Pull Requests

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Commands to list pull requests in a repository. Supports filtering by state, author, and pagination. Defaults to open PRs.

```bash
# List open PRs in a repository (default state: OPEN)
list_pull_requests --repository "my-repo"
```

```bash
# List all PRs regardless of state
list_pull_requests --repository "my-repo" --state "ALL"
```

```bash
# Find PRs by a specific author
list_pull_requests --repository "my-repo" --author "john.doe"
```

```bash
# List merged PRs with pagination
list_pull_requests --repository "my-repo" --state "MERGED" --limit 10 --start 0
```

--------------------------------

### Search Code or Filenames

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Searches code and filenames across all accessible repositories using the Bitbucket Search API. Supports project/repository scoping and a 'file' mode for exact filename matching.

```APIDOC
## MCP Tool: `search`

Searches code and filenames across all accessible repositories using the Bitbucket Search API (`/rest/search/latest/search`). Supports project/repository scoping and a `"file"` mode that wraps the query in quotes for exact filename matching.

### Method
tools/call

### Parameters
#### Arguments
- **query** (string) - Required - The search query.
- **project** (string) - Optional - The project key to scope the search.
- **repository** (string) - Optional - The repository slug to scope the search.
- **type** (string) - Optional - The search type, e.g., `"code"` or `"file"`. Defaults to `"code"`.
- **limit** (integer) - Optional - The maximum number of results to return.

### Request Example (Code Search)
```json
{
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "getUserToken",
      "project": "MYPROJ",
      "repository": "my-app",
      "type": "code",
      "limit": 10
    }
  }
}
```

### Request Example (File Name Search)
```json
{
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "README.md",
      "type": "file",
      "limit": 5
    }
  }
}
```

### Response
#### Success Response
- **query** (string) - The constructed search query.
- **originalQuery** (string) - The original search query.
- **total** (integer) - The total number of results found.
- **showing** (integer) - The number of results currently shown.
- **results** (array) - An array of search result objects, each containing repository and file information, hit count, and hit contexts.
```

--------------------------------

### Full Pull Request Workflow

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Execute a complete pull request workflow including reviewing the diff, approving, and merging. This demonstrates a common sequence of operations.

```bash
get_diff --repository "my-repo" --prId 123
approve_pull_request --repository "my-repo" --prId 123
merge_pull_request --repository "my-repo" --prId 123 --strategy "squash"
```

--------------------------------

### List Branches MCP Tool

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Lists branches in a repository, identifies the default branch, and supports partial-name filtering. Specify 'filterText' for partial matching.

```json
{
  "method": "tools/call",
  "params": {
    "name": "list_branches",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "filterText": "feature",
      "limit": 25
    }
  }
}
```

--------------------------------

### Combine Commit Filters

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Combine multiple filters such as project, repository, branch, and author with `list_commits` for precise commit history retrieval.

```bash
list_commits --project "MYPROJECT" --repository "my-repo" --branch "main" --author "jane"
```

--------------------------------

### List Dashboard Pull Requests using MCP Tool

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Lists pull requests across all repositories for the authenticated user, suitable for personal review queues. Supports filtering by state, role, and other criteria.

```json
{
  "method": "tools/call",
  "params": {
    "name": "get_dashboard_pull_requests",
    "arguments": {
      "state": "OPEN",
      "role": "REVIEWER",
      "participantStatus": "UNAPPROVED",
      "order": "NEWEST",
      "limit": 25
    }
  }
}
```

```json
{
  "name": "get_dashboard_pull_requests",
  "arguments": {
    "state": "MERGED",
    "role": "AUTHOR",
    "closedSince": 1719878400000,
    "limit": 10
  }
}
```

```text
// Response: standard Bitbucket paginated PR list from /dashboard/pull-requests
```

--------------------------------

### get_activities

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Retrieve the complete activity timeline for a pull request, including comments, reviews, commits, and other events.

```APIDOC
## get_activities

### Description
Gets the complete activity timeline for a pull request including comments, reviews, commits, and other events.

### Parameters
- `project` (string) - Optional - Bitbucket project key (uses BITBUCKET_DEFAULT_PROJECT if not provided)
- `repository` (string) - Required - Repository slug
- `prId` (integer) - Required - Pull request ID
```

--------------------------------

### get_reviews

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Fetches the review history, approval status, and reviewer feedback for a pull request to understand its review state.

```APIDOC
## get_reviews

### Description
Fetches the review history, approval status, and reviewer feedback for a pull request to understand its review state.

### Parameters
- `project` (string) - Optional - Bitbucket project key (uses BITBUCKET_DEFAULT_PROJECT if not provided)
- `repository` (string) - Required - Repository slug
- `prId` (integer) - Required - Pull request ID
```

--------------------------------

### List Pull Requests

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Lists PRs in a repository with server-side filtering by state and direction, plus client-side author filtering.

```json
{
  "method": "tools/call",
  "params": {
    "name": "list_pull_requests",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "state": "OPEN",
      "author": "alice",
      "direction": "INCOMING",
      "limit": 10
    }
  }
}
```

```json
{
  "project": "MYPROJ",
  "repository": "my-app",
  "state": "OPEN",
  "authorFilter": "alice",
  "total": 2,
  "showing": 2,
  "pullRequests": [
    {
      "id": 42,
      "title": "Feature: add OAuth2 login",
      "state": "OPEN",
      "author": "Alice Smith",
      "sourceBranch": "feature/oauth2-login",
      "targetBranch": "main",
      "reviewers": [{ "name": "bob", "status": "APPROVED" }]
    }
  ]
}
```

--------------------------------

### Filter Branches by Name

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Use the `list_branches` command to filter branches based on a provided text string. Specify the project and repository to narrow down the search.

```bash
list_branches --project "MYPROJECT" --repository "my-repo" --filterText "feature"
```

--------------------------------

### Create Pull Request

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Creates a new pull request. Automatically fetches and merges default reviewers unless `includeDefaultReviewers` is `false`. Supports cross-repository PRs via `sourceProject`/`sourceRepository`.

```json
{
  "method": "tools/call",
  "params": {
    "name": "create_pull_request",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "title": "Feature: add OAuth2 login",
      "description": "Implements OAuth2 via PKCE flow.\n\n**Testing**: `npm test`",
      "sourceBranch": "feature/oauth2-login",
      "targetBranch": "main",
      "reviewers": ["alice", "bob"],
      "includeDefaultReviewers": true
    }
  }
}
```

--------------------------------

### Create a Pull Request in Bitbucket Server

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Creates a new pull request for code changes. Specify project, repository, title, branches, and optional reviewers. The `includeDefaultReviewers` parameter defaults to true.

```json
{
  "project": "your_project_key",
  "repository": "your_repo_slug",
  "title": "New feature implementation",
  "description": "This PR introduces a new feature that enhances user experience.",
  "sourceBranch": "feature-branch",
  "targetBranch": "main",
  "reviewers": ["user1", "user2"],
  "includeDefaultReviewers": true
}
```

--------------------------------

### Publish PR Review

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Publish all pending (draft) comments on a PR in a single batch using `publish_review`. Optionally sets the reviewer's status and attaches an overview comment.

```json
{
  "method": "tools/call",
  "params": {
    "name": "publish_review",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "prId": 42,
      "participantStatus": "NEEDS_WORK",
      "commentText": "Two blocking issues need resolving before this can merge (see inline comments)."
    }
  }
}
```

--------------------------------

### Add Single Custom HTTP Header

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Add a single custom HTTP header by setting the BITBUCKET_CUSTOM_HEADERS environment variable with a key-value pair. This is useful for security tokens or proxy configurations.

```json
{
  "env": {
    "BITBUCKET_CUSTOM_HEADERS": "X-Zero-Trust-Token=your-token-here"
  }
}
```

--------------------------------

### parseCustomHeaders Utility

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Parses a comma-separated string of custom headers into a plain JavaScript object. This utility is useful for processing the `BITBUCKET_CUSTOM_HEADERS` environment variable.

```APIDOC
## `parseCustomHeaders`

Parses a comma-separated `Key=value,Key2=value2` string into a plain headers object. Values may themselves contain `=` characters (e.g. Base64 tokens). Returns `{}` for blank or undefined input.

```typescript
import { parseCustomHeaders } from './src/headers.js';

// Single header
parseCustomHeaders('X-Zero-Trust-Token=abc123');
// => { 'X-Zero-Trust-Token': 'abc123' }

// Multiple headers, value with embedded '='
parseCustomHeaders('Authorization=Bearer dG9rZW4=,X-Proxy-ID=proxy-01');
// => { Authorization: 'Bearer dG9rZW4=', 'X-Proxy-ID': 'proxy-01' }

// Blank / undefined
parseCustomHeaders(undefined); // => {}
parseCustomHeaders('');        // => {}

// Used internally during construction:
const server = new BitbucketServer({
  baseUrl: 'https://bitbucket.example.com',
  token: 'mytoken',
  customHeaders: parseCustomHeaders(process.env.BITBUCKET_CUSTOM_HEADERS),
});
```
```

--------------------------------

### List Branches

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Lists branches in a repository, identifies the default branch, and supports partial-name filtering.

```APIDOC
## MCP Tool: `list_branches`

Lists branches in a repository, identifies the default branch, and supports partial-name filtering.

### Method
tools/call

### Parameters
#### Arguments
- **project** (string) - Required - The project key.
- **repository** (string) - Required - The repository slug.
- **filterText** (string) - Optional - Filters branches by name (partial match).
- **limit** (integer) - Optional - The maximum number of branches to return. Defaults to 25.

### Request Example
```json
{
  "method": "tools/call",
  "params": {
    "name": "list_branches",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "filterText": "feature",
      "limit": 25
    }
  }
}
```

### Response
#### Success Response
- **defaultBranch** (string) - The name of the default branch.
- **total** (integer) - The total number of branches found.
- **branches** (array) - An array of branch objects, each containing name, ID, latest commit, and default status.
```

--------------------------------

### get_reviews

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Retrieves only APPROVED/REVIEWED activity entries from the PR activity stream, providing a concise view of review decisions.

```APIDOC
## MCP Tool: `get_reviews`

### Description
Returns only APPROVED/REVIEWED activity entries from the PR activity stream, providing a concise view of review decisions.

### Method
`tools/call`

### Parameters
#### Arguments
- **project** (string) - Required - The project identifier.
- **repository** (string) - Required - The repository name.
- **prId** (integer) - Required - The pull request ID.

### Response
#### Success Response
An array of activity objects with action "APPROVED" or "REVIEWED", each containing user info and timestamp.
```

--------------------------------

### get_pull_request

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Retrieves full PR metadata: status, reviewers with their approval state, source/target refs, and all Bitbucket-managed fields.

```APIDOC
## MCP Tool: `get_pull_request`

### Description
Retrieves full PR metadata: status, reviewers with their approval state, source/target refs, and all Bitbucket-managed fields.

### Method
`tools/call`

### Parameters
#### Arguments
- **project** (string) - Required - The project the repository belongs to.
- **repository** (string) - Required - The repository name.
- **prId** (integer) - Required - The ID of the pull request to retrieve.

### Request Example
```json
{
  "method": "tools/call",
  "params": {
    "name": "get_pull_request",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "prId": 42
    }
  }
}
```

### Response
#### Success Response
Includes: id, title, state ("OPEN"|"MERGED"|"DECLINED"), version (needed for merge/decline/optimistic-lock calls), reviewers[].status ("APPROVED"|"UNAPPROVED"|"NEEDS_WORK"), links, etc.
```

--------------------------------

### Update Pull Request

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Updates an existing PR's title, description, or reviewer list using a read-modify-write pattern so unchanged fields are preserved.

```json
{
  "method": "tools/call",
  "params": {
    "name": "update_pull_request",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "prId": 42,
      "title": "Feature: add OAuth2 login (revised)",
      "reviewers": ["alice", "bob", "carol"]
    }
  }
}
```

--------------------------------

### get_file_content

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Retrieve the content of specific files from repositories, supporting large files through pagination.

```APIDOC
## get_file_content

### Description
Retrieve the content of specific files from repositories with support for large files through pagination.

### Parameters
- `project` (string) - Optional - Bitbucket project key (uses BITBUCKET_DEFAULT_PROJECT if not provided)
- `repository` (string) - Required - Repository slug
- `filePath` (string) - Required - Path to the file in the repository
- `branch` (string) - Optional - Branch or commit hash (defaults to main/master)
- `limit` (integer) - Optional - Maximum lines per request (default: 100, max: 1000)
- `start` (integer) - Optional - Starting line number for pagination (default: 0)
```

--------------------------------

### create_pull_request

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Creates a new pull request. Automatically fetches and merges default reviewers configured for the target branch unless `includeDefaultReviewers` is `false`. Supports cross-repository (fork) PRs via `sourceProject`/`sourceRepository`.

```APIDOC
## MCP Tool: `create_pull_request`

### Description
Creates a new pull request. Automatically fetches and merges default reviewers configured for the target branch unless `includeDefaultReviewers` is `false`. Supports cross-repository (fork) PRs via `sourceProject`/`sourceRepository`.

### Method
`tools/call`

### Parameters
#### Arguments
- **project** (string) - Required - The project the repository belongs to.
- **repository** (string) - Required - The repository name.
- **title** (string) - Required - The title of the pull request.
- **description** (string) - Optional - The description of the pull request.
- **sourceBranch** (string) - Required - The source branch for the pull request.
- **targetBranch** (string) - Required - The target branch for the pull request.
- **reviewers** (array[string]) - Optional - A list of reviewers to assign to the pull request.
- **includeDefaultReviewers** (boolean) - Optional - Whether to include default reviewers. Defaults to true.

### Request Example
```json
{
  "method": "tools/call",
  "params": {
    "name": "create_pull_request",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "title": "Feature: add OAuth2 login",
      "description": "Implements OAuth2 via PKCE flow.\n\n**Testing**: `npm test`",
      "sourceBranch": "feature/oauth2-login",
      "targetBranch": "main",
      "reviewers": ["alice", "bob"],
      "includeDefaultReviewers": true
    }
  }
}
```

### Response
#### Success Response
Full Bitbucket PR object including id, links, reviewers, version, etc.
```

--------------------------------

### get_diff

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Retrieves the unified diff for a PR as plain text. Supports configurable context lines and per-file line truncation (60% head / 40% tail when truncated) to handle large changesets.

```APIDOC
## MCP Tool: `get_diff`

### Description
Retrieves the unified diff for a PR as plain text. Supports configurable context lines and per-file line truncation (60% head / 40% tail when truncated) to handle large changesets.

### Method
`tools/call`

### Parameters
#### Arguments
- **project** (string) - Required - The project the repository belongs to.
- **repository** (string) - Required - The repository name.
- **prId** (integer) - Required - The ID of the pull request.
- **contextLines** (integer) - Optional - The number of context lines to include in the diff. Defaults to a reasonable value if not specified.
- **maxLinesPerFile** (integer) - Optional - The maximum number of lines to show per file. If exceeded, the file will be truncated. Defaults to a reasonable value if not specified.

### Request Example
```json
{
  "method": "tools/call",
  "params": {
    "name": "get_diff",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "prId": 42,
      "contextLines": 5,
      "maxLinesPerFile": 200
    }
  }
}
```

### Response
#### Success Response
Content of the response is a raw unified diff string. Example:
```diff
diff --git a/src/auth.ts b/src/auth.ts
index abc123..def456 100644
--- a/src/auth.ts
+++ b/src/auth.ts
@@ -10,6 +10,12 @@
...
[*** FILE TRUNCATED: 340 lines hidden from src/auth.ts ***]
[*** File had 540 total lines, showing first 120 and last 80 ***]
```
```

--------------------------------

### Filter Commits by Author

Source: https://github.com/garc33/bitbucket-server-mcp-server/blob/main/README.md

Use the `list_commits` command with the `--author` flag to filter commits made by a specific user. This helps in tracking contributions.

```bash
list_commits --repository "my-repo" --author "john.doe"
```

--------------------------------

### List Commits MCP Tool

Source: https://context7.com/garc33/bitbucket-server-mcp-server/llms.txt

Lists commits on a branch with optional author filtering. Author filtering is a case-insensitive partial match applied client-side. Supports specifying project, repository, branch, author, and limit.

```json
{
  "method": "tools/call",
  "params": {
    "name": "list_commits",
    "arguments": {
      "project": "MYPROJ",
      "repository": "my-app",
      "branch": "main",
      "author": "alice",
      "limit": 10
    }
  }
}
```