execute_native_query

Run custom SQL queries directly against Metabase databases to retrieve data not available in saved cards. Execute SELECT statements for ad-hoc analysis while managing resource usage.

Instructions

⚠️ [MODERATE RISK] Execute an ad-hoc native SQL query directly against a database. Use this when you need to run custom SQL that doesn't exist as a saved card. Risk: Moderate - executes arbitrary SQL (read-only with API key, but can be slow or resource-intensive). Always validate SQL before executing.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`databaseId`	Yes	The ID of the database to query
`query`	Yes	The SQL query to execute (SELECT statements only recommended)

Implementation Reference

src/server/handlers/queryHandlers.js:16-48 (handler)

The core handler function that validates inputs, constructs a native query payload, sends it to Metabase's /api/dataset endpoint via POST, and returns formatted results including the query and JSON-stringified response.

  async executeNativeQuery(databaseId, query) {
    Validators.validateDatabaseId(databaseId);
    Validators.validateQuery(query);
    
    this.logger.debug('Executing native query', { databaseId, queryLength: query.length });
    
    const body = {
      database: databaseId,
      type: 'native',
      native: {
        query: query,
      },
    };

    const results = await this.apiClient.makeRequest('/api/dataset', {
      method: 'POST',
      body: JSON.stringify(body),
    });
    
    return {
      content: [
        {
          type: 'text',
          text: `Query Execution Results:
Database: ${databaseId}
Query: ${query}

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

src/server/config/toolDefinitions.js:197-216 (schema)

Defines the tool schema including name, description, and inputSchema specifying required integer databaseId and string query parameters with validation constraints.

{
  name: 'execute_native_query',
  description: '⚠️ [MODERATE RISK] Execute an ad-hoc native SQL query directly against a database. Use this when you need to run custom SQL that doesn\'t exist as a saved card. Risk: Moderate - executes arbitrary SQL (read-only with API key, but can be slow or resource-intensive). Always validate SQL before executing.',
  inputSchema: {
    type: 'object',
    properties: {
      databaseId: {
        type: 'integer',
        description: 'The ID of the database to query',
        minimum: 1,
      },
      query: {
        type: 'string',
        description: 'The SQL query to execute (SELECT statements only recommended)',
        minLength: 1,
      },
    },
    required: ['databaseId', 'query'],
  },
},

src/server/MetabaseMCPServer.js:206-207 (registration)
Registers the tool handler in the MCP server's executeTool switch statement, dispatching calls to the QueryHandlers instance's executeNativeQuery method.
```
case 'execute_native_query':
  return await this.queryHandlers.executeNativeQuery(args.databaseId, args.query);
```

Metabase MCP Server