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