execute_card_query

Execute saved Metabase card queries to retrieve data results. Use this tool to run pre-defined queries with optional parameters for filtering.

Instructions

▶️ [MODERATE RISK] Execute a saved card query and return results. Use this to get actual data from a card. May take time for complex queries. Risk: Moderate - executes queries that may be slow or resource-intensive. Does not modify data.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`cardId`	Yes	The ID of the card to execute
`parameters`	No	Query parameters (e.g., date filters, IDs)

Implementation Reference

src/server/handlers/cardHandlers.js:103-126 (handler)

The core handler function that implements the execute_card_query tool. It validates the cardId, constructs query parameters, makes a POST request to Metabase's /api/card/{cardId}/query endpoint, and formats the results as MCP content.

  async executeCardQuery(cardId, parameters = {}) {
    Validators.validateCardId(cardId);
    
    this.logger.debug('Executing card query', { cardId, parameters });
    
    const queryParams = new URLSearchParams();
    Object.entries(parameters).forEach(([key, value]) => {
      queryParams.append(key, value);
    });

    const results = await this.apiClient.makeRequest(`/api/card/${cardId}/query?${queryParams}`, {
      method: 'POST',
    });
    
    return {
      content: [
        {
          type: 'text',
          text: `Query Results for Card ${cardId}:
${JSON.stringify(results, null, 2)}`,
        },
      ],
    };
  }

src/server/config/toolDefinitions.js:43-62 (schema)

The JSON schema definition for the execute_card_query tool, specifying input validation for cardId (required integer) and optional parameters object. Used for tool listing and validation.

{
  name: 'execute_card_query',
  description: '▶️ [MODERATE RISK] Execute a saved card query and return results. Use this to get actual data from a card. May take time for complex queries. Risk: Moderate - executes queries that may be slow or resource-intensive. Does not modify data.',
  inputSchema: {
    type: 'object',
    properties: {
      cardId: {
        type: 'integer',
        description: 'The ID of the card to execute',
        minimum: 1,
      },
      parameters: {
        type: 'object',
        description: 'Query parameters (e.g., date filters, IDs)',
        additionalProperties: true,
      },
    },
    required: ['cardId'],
  },
},

src/server/MetabaseMCPServer.js:172-173 (registration)
Registration of the execute_card_query tool in the server's executeTool switch statement, which dispatches tool calls to the appropriate handler method.
```
case 'execute_card_query':
  return await this.cardHandlers.executeCardQuery(args.cardId, args.parameters);
```

Metabase MCP Server