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
- 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); - 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), }); }