execute_query_builder_card

Run Metabase query builder cards with custom filters and aggregations to analyze data using specific parameters.

Instructions

⚙️ [MODERATE RISK] Execute a query-builder card with specific parameters. Use this to run query builder cards with custom filters and aggregations. Risk: Moderate - executes queries that may be slow or resource-intensive.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`cardId`	Yes	The card ID
`parameters`	Yes	Query parameters object with filters, aggregations, breakouts

Implementation Reference

src/server/handlers/cardHandlers.js:131-178 (handler)

The primary handler function that implements the core logic for the 'execute_query_builder_card' MCP tool. It validates the card ID, fetches the base card details, modifies the query builder structure with provided parameters, executes the query via Metabase's /api/dataset endpoint, and returns formatted results.

  async executeQueryBuilderCard(cardId, parameters) {
    Validators.validateCardId(cardId);
    
    this.logger.debug('Executing query builder card', { cardId, parameters });
    
    // First, get the base card to understand its structure
    const baseCard = await this.apiClient.makeRequest(`/api/card/${cardId}`);
    
    if (baseCard.dataset_query.type !== 'query') {
      throw new Error('Card is not a query-builder card');
    }
    
    // Create a modified dataset query with the provided parameters
    const modifiedQuery = {
      ...baseCard.dataset_query,
      query: {
        ...baseCard.dataset_query.query,
        ...parameters,
      },
    };
    
    // Execute the query using the dataset endpoint
    const body = {
      database: baseCard.dataset_query.database,
      type: 'query',
      query: modifiedQuery.query,
    };

    const results = await this.apiClient.makeRequest('/api/dataset', {
      method: 'POST',
      body: JSON.stringify(body),
    });
    
    return {
      content: [
        {
          type: 'text',
          text: `Query Builder Card Execution Results:
Card ID: ${cardId}
Parameters Applied:
${JSON.stringify(parameters, null, 2)}

Results:
${JSON.stringify(results, null, 2)}`,
        },
      ],
    };
  }

src/server/MetabaseMCPServer.js:174-175 (registration)
The registration/dispatch logic in the MCP server's executeTool method that maps the tool name 'execute_query_builder_card' to the corresponding handler method.
```
case 'execute_query_builder_card':
  return await this.cardHandlers.executeQueryBuilderCard(args.cardId, args.parameters);
```

src/server/config/toolDefinitions.js:320-338 (schema)

The tool definition including name, description, and input schema (JSON Schema) for input validation in the MCP server.

  name: 'execute_query_builder_card',
  description: '⚙️ [MODERATE RISK] Execute a query-builder card with specific parameters. Use this to run query builder cards with custom filters and aggregations. Risk: Moderate - executes queries that may be slow or resource-intensive.',
  inputSchema: {
    type: 'object',
    properties: {
      cardId: {
        type: 'integer',
        description: 'The card ID',
        minimum: 1,
      },
      parameters: {
        type: 'object',
        description: 'Query parameters object with filters, aggregations, breakouts',
        additionalProperties: true,
      },
    },
    required: ['cardId', 'parameters'],
  },
},

src/client/MetabaseClient.js:557-591 (helper)

Supporting client method that performs the core API calls for executing query builder cards, mirroring the handler logic but used as a utility in other contexts.

async executeQueryBuilderCard(cardId, parameters) {
  Validators.validateCardId(cardId);

  // First, get the base card to understand its structure
  const baseCard = await this.makeRequest(`/api/card/${cardId}`);
  
  if (baseCard.dataset_query.type !== 'query') {
    throw new ValidationError(
      'Card is not a query-builder card',
      'cardId',
      cardId
    );
  }
  
  // Create a modified dataset query with the provided parameters
  const modifiedQuery = {
    ...baseCard.dataset_query,
    query: {
      ...baseCard.dataset_query.query,
      ...parameters,
    },
  };
  
  // Execute the query using the dataset endpoint
  const body = {
    database: baseCard.dataset_query.database,
    type: 'query',
    query: modifiedQuery.query,
  };

  return await this.makeRequest('/api/dataset', {
    method: 'POST',
    body: JSON.stringify(body),
  });
}

Metabase MCP Server