execute_query_builder_card
Run Metabase query builder cards with custom filters and aggregations to retrieve specific data from your analytics platform.
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 execute_query_builder_card tool. It fetches the base card details, validates it's a query-builder card, merges provided parameters into the query, executes the modified query via Metabase's /api/dataset endpoint, and returns formatted results including parameters and data.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)Tool dispatch/registration in the main MCP server switch statement, routing calls to the cardHandlers implementation.case 'execute_query_builder_card': return await this.cardHandlers.executeQueryBuilderCard(args.cardId, args.parameters);
- Tool definition including name, description, and input schema for validation (cardId: integer >=1, parameters: object). Exported as part of TOOL_DEFINITIONS array used for MCP tool registration.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'], }, },