explain_query
Analyze MongoDB query execution plans to identify performance bottlenecks, understand index usage, and optimize slow database queries.
Instructions
Get the execution plan for a query.
Helps understand:
How MongoDB will execute the query
Which indexes will be used
Number of documents examined
Execution stages and timing
Use this to optimize slow queries.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| database | No | Database name (optional if default database is configured) | |
| collection | Yes | Collection name | |
| filter | Yes | MongoDB query filter to explain | |
| projection | No | MongoDB projection (optional) | |
| sort | No | MongoDB sort specification (optional) |
Implementation Reference
- src/index.ts:1241-1277 (handler)Handler for the 'explain_query' tool. Builds a MongoDB find query based on provided filter, projection, and sort, then executes .explain() to retrieve the query execution plan, and returns it as formatted JSON.
case 'explain_query': { const { database, collection, filter, projection, sort } = request.params .arguments as { database?: string; collection: string; filter: object; projection?: object; sort?: Sort; }; const dbName = database || this.defaultDatabase; if (!dbName) { throw new McpError( ErrorCode.InvalidRequest, 'Database name is required when no default database is configured' ); } const db = client.db(dbName); let query = db.collection(collection).find(filter); if (projection) { query = query.project(projection); } if (sort) { query = query.sort(sort); } const explanation = await query.explain(); return { content: [ { type: 'text', text: JSON.stringify(explanation, null, 2), }, ], }; } - src/index.ts:600-637 (registration)Registration of the 'explain_query' tool in the ListToolsRequestSchema handler. Includes the tool name, description, and input schema definition.
{ name: 'explain_query', description: `Get the execution plan for a query. Helps understand: - How MongoDB will execute the query - Which indexes will be used - Number of documents examined - Execution stages and timing Use this to optimize slow queries.`, inputSchema: { type: 'object', properties: { database: { type: 'string', description: 'Database name (optional if default database is configured)', }, collection: { type: 'string', description: 'Collection name', }, filter: { type: 'object', description: 'MongoDB query filter to explain', }, projection: { type: 'object', description: 'MongoDB projection (optional)', }, sort: { type: 'object', description: 'MongoDB sort specification (optional)', }, }, required: ['collection', 'filter'], }, }, - src/index.ts:611-637 (schema)Input schema definition for the 'explain_query' tool, specifying parameters like database, collection, filter, projection, and sort.
inputSchema: { type: 'object', properties: { database: { type: 'string', description: 'Database name (optional if default database is configured)', }, collection: { type: 'string', description: 'Collection name', }, filter: { type: 'object', description: 'MongoDB query filter to explain', }, projection: { type: 'object', description: 'MongoDB projection (optional)', }, sort: { type: 'object', description: 'MongoDB sort specification (optional)', }, }, required: ['collection', 'filter'], }, },