Bitbucket Cloud MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:1058-1070 (handler)

  Main handler case in ToolHandler.handleTool for the 'trigger_pipeline' tool. Parses arguments using Zod schema and calls PipelinesAPI.trigger to execute the pipeline trigger.

  case 'trigger_pipeline': {
    const params = toolSchemas.trigger_pipeline.parse(args);
    return this.pipelines.trigger({
      workspace: params.workspace,
      repo_slug: params.repo_slug,
      target: {
        type: 'pipeline_ref_target',
        ref_type: params.ref_type,
        ref_name: params.ref_name,
      },
      variables: params.variables,
    });
  }

• src/tools/index.ts:265-280 (schema)

  Zod schema definition for validating inputs to the trigger_pipeline tool.

  trigger_pipeline: z.object({
    workspace: z.string().describe('The workspace slug'),
    repo_slug: z.string().describe('The repository slug'),
    ref_type: z.enum(['branch', 'tag', 'bookmark']).describe('Reference type'),
    ref_name: z.string().describe('Reference name (branch/tag name)'),
    variables: z
      .array(
        z.object({
          key: z.string(),
          value: z.string(),
          secured: z.boolean().optional(),
        })
      )
      .optional()
      .describe('Pipeline variables'),
  }),

• src/tools/index.ts:801-831 (registration)

  Tool registration in toolDefinitions array, including name, description, and MCP inputSchema.

  {
    name: 'trigger_pipeline',
    description: 'Trigger a new pipeline run on a branch, tag, or bookmark.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        workspace: { type: 'string', description: 'The workspace slug' },
        repo_slug: { type: 'string', description: 'The repository slug' },
        ref_type: {
          type: 'string',
          enum: ['branch', 'tag', 'bookmark'],
          description: 'Reference type',
        },
        ref_name: { type: 'string', description: 'Reference name (branch/tag name)' },
        variables: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              key: { type: 'string' },
              value: { type: 'string' },
              secured: { type: 'boolean' },
            },
            required: ['key', 'value'],
          },
          description: 'Pipeline variables',
        },
      },
      required: ['workspace', 'repo_slug', 'ref_type', 'ref_name'],
    },
  },

• src/api/pipelines.ts:39-54 (helper)

  PipelinesAPI.trigger method, which constructs the request body and makes the POST call to Bitbucket API to trigger the pipeline.

  async trigger(params: TriggerPipelineParams): Promise<BitbucketPipeline> {
    const { workspace, repo_slug, target, variables } = params;
  
    const body: Record<string, unknown> = {
      target,
    };
  
    if (variables && variables.length > 0) {
      body.variables = variables;
    }
  
    return this.client.post<BitbucketPipeline>(
      `/repositories/${workspace}/${repo_slug}/pipelines`,
      body
    );
  }

• src/types/index.ts:356-369 (schema)

  TypeScript interface defining the TriggerPipelineParams used by PipelinesAPI.trigger.

  export interface TriggerPipelineParams {
    workspace: string;
    repo_slug: string;
    target: {
      type: 'pipeline_ref_target';
      ref_type: 'branch' | 'tag' | 'bookmark';
      ref_name: string;
    };
    variables?: Array<{
      key: string;
      value: string;
      secured?: boolean;
    }>;
  }