Metabase MCP Server

Instructions

Implementation Reference

• src/server/handlers/cardHandlers.js:183-238 (handler)

  The core handler function for 'get_generated_sql'. Fetches the query-builder card by ID, merges provided parameters into the query structure, posts to Metabase /api/dataset endpoint to generate the SQL, extracts the SQL from response, and formats a response with the generated SQL.

    async getGeneratedSQL(cardId, parameters) {
      Validators.validateCardId(cardId);
      
      this.logger.debug('Getting generated SQL', { cardId, parameters });
      
      // Get the base card
      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,
        },
      };
      
      // Use the query endpoint to get the generated SQL
      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),
      });
      
      // Extract SQL if available
      const sql = results.query || results.native?.query || 'SQL not available in response';
      
      return {
        content: [
          {
            type: 'text',
            text: `Generated SQL for Query Builder Card:
  Card ID: ${cardId}
  Card Name: ${baseCard.name}
  
  Parameters Applied:
  ${JSON.stringify(parameters, null, 2)}
  
  Generated SQL:
  ${sql}
  
  Full Query Response:
  ${JSON.stringify(results, null, 2)}`,
          },
        ],
      };
    }

• src/server/config/toolDefinitions.js:340-358 (schema)

  Defines the tool schema including name, description, and inputSchema for validation (cardId: integer, parameters: object). Used by MCP server for tool listing and validation.

    name: 'get_generated_sql',
    description: '📝 [MODERATE RISK] Get the generated SQL for a query-builder card with parameters. Use this to see the actual SQL that Metabase generates from query builder parameters. Risk: Moderate - executes queries to generate SQL.',
    inputSchema: {
      type: 'object',
      properties: {
        cardId: {
          type: 'integer',
          description: 'The card ID',
          minimum: 1,
        },
        parameters: {
          type: 'object',
          description: 'Query parameters object',
          additionalProperties: true,
        },
      },
      required: ['cardId', 'parameters'],
    },
  },

• src/server/MetabaseMCPServer.js:176-177 (registration)

  Registers the tool in the MCP server's executeTool switch statement, dispatching calls to the CardHandlers.getGeneratedSQL method.

  case 'get_generated_sql':
    return await this.cardHandlers.getGeneratedSQL(args.cardId, args.parameters);