Bitbucket MCP Server

Instructions

Implementation Reference

• src/handlers/pull-request-handlers.ts:254-335 (handler)

  The core handler function `handleCreatePullRequest` that implements the tool logic: validates input using type guard, constructs API payload for Bitbucket Cloud/Server, posts to create PR, formats response.

  async handleCreatePullRequest(args: any) {
    if (!isCreatePullRequestArgs(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for create_pull_request'
      );
    }
  
    const { workspace, repository, title, source_branch, destination_branch, description, reviewers, close_source_branch } = args;
  
    try {
      let apiPath: string;
      let requestBody: any;
  
      if (this.apiClient.getIsServer()) {
        // Bitbucket Server API
        apiPath = `/rest/api/1.0/projects/${workspace}/repos/${repository}/pull-requests`;
        requestBody = {
          title,
          description: description || '',
          fromRef: {
            id: `refs/heads/${source_branch}`,
            repository: {
              slug: repository,
              project: {
                key: workspace
              }
            }
          },
          toRef: {
            id: `refs/heads/${destination_branch}`,
            repository: {
              slug: repository,
              project: {
                key: workspace
              }
            }
          },
          reviewers: reviewers?.map(r => ({ user: { name: r } })) || []
        };
      } else {
        // Bitbucket Cloud API
        apiPath = `/repositories/${workspace}/${repository}/pullrequests`;
        requestBody = {
          title,
          description: description || '',
          source: {
            branch: {
              name: source_branch
            }
          },
          destination: {
            branch: {
              name: destination_branch
            }
          },
          close_source_branch: close_source_branch || false,
          reviewers: reviewers?.map(r => ({ username: r })) || []
        };
      }
  
      const pr = await this.apiClient.makeRequest<any>('post', apiPath, requestBody);
      
      const formattedResponse = this.apiClient.getIsServer() 
        ? formatServerResponse(pr as BitbucketServerPullRequest, undefined, this.baseUrl)
        : formatCloudResponse(pr as BitbucketCloudPullRequest);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              message: 'Pull request created successfully',
              pull_request: formattedResponse
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return this.apiClient.handleApiError(error, `creating pull request in ${workspace}/${repository}`);
    }
  }

• src/tools/definitions.ts:59-101 (schema)

  MCP tool definition including name, description, and JSON inputSchema for the create_pull_request tool, returned by listTools.

  {
    name: 'create_pull_request',
    description: 'Create a new pull request',
    inputSchema: {
      type: 'object',
      properties: {
        workspace: {
          type: 'string',
          description: 'Bitbucket workspace/project key (e.g., "PROJ")',
        },
        repository: {
          type: 'string',
          description: 'Repository slug (e.g., "my-repo")',
        },
        title: {
          type: 'string',
          description: 'Title of the pull request',
        },
        source_branch: {
          type: 'string',
          description: 'Source branch name',
        },
        destination_branch: {
          type: 'string',
          description: 'Destination branch name (e.g., "main", "master")',
        },
        description: {
          type: 'string',
          description: 'Description of the pull request (optional)',
        },
        reviewers: {
          type: 'array',
          items: { type: 'string' },
          description: 'Array of reviewer usernames/emails (optional)',
        },
        close_source_branch: {
          type: 'boolean',
          description: 'Whether to close source branch after merge (optional, default: false)',
        },
      },
      required: ['workspace', 'repository', 'title', 'source_branch', 'destination_branch'],
    },
  },

• src/types/guards.ts:30-51 (schema)

  Type guard `isCreatePullRequestArgs` for runtime validation of tool arguments in the handler.

  export const isCreatePullRequestArgs = (
    args: any
  ): args is {
    workspace: string;
    repository: string;
    title: string;
    source_branch: string;
    destination_branch: string;
    description?: string;
    reviewers?: string[];
    close_source_branch?: boolean;
  } =>
    typeof args === 'object' &&
    args !== null &&
    typeof args.workspace === 'string' &&
    typeof args.repository === 'string' &&
    typeof args.title === 'string' &&
    typeof args.source_branch === 'string' &&
    typeof args.destination_branch === 'string' &&
    (args.description === undefined || typeof args.description === 'string') &&
    (args.reviewers === undefined || Array.isArray(args.reviewers)) &&
    (args.close_source_branch === undefined || typeof args.close_source_branch === 'boolean');

• src/index.ts:100-101 (registration)

  Server request handler switch case that dispatches 'create_pull_request' tool calls to the appropriate handler method.

  case 'create_pull_request':
    return this.pullRequestHandlers.handleCreatePullRequest(request.params.arguments);