MongoDB MCP Server

Instructions

Implementation Reference

• src/index.ts:1359-1384 (handler)

  Handler for the count_documents tool. Extracts parameters, connects to the MongoDB database, executes countDocuments(filter) on the specified collection, and returns the count in JSON format.

  case 'count_documents': {
    const { database, collection, filter = {} } = request.params.arguments as {
      database?: string;
      collection: string;
      filter?: object;
    };
    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);
    const count = await db.collection(collection).countDocuments(filter);
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({ count }, null, 2),
        },
      ],
    };
  }

• src/index.ts:757-792 (registration)

  Tool registration entry for count_documents, defining its name, description, and input schema for the ListToolsRequestSchema handler.

            name: 'count_documents',
            description: `Count documents in a collection that match a filter.
    
  Benefits:
  - More efficient than retrieving full documents
  - Good for understanding data volume
  - Can help planning query strategies
  - Optimize pagination implementation
  
  Example:
  use_mcp_tool with
    server_name: "mongodb",
    tool_name: "count_documents",
    arguments: {
      "collection": "users",
      "filter": { "active": true, "age": { "$gte": 21 } }
    }`,
            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 (optional, defaults to count all documents)',
                },
              },
              required: ['collection'],
            },
          },

• src/index.ts:774-791 (schema)

  Input schema definition for the count_documents tool, specifying parameters: database (optional), collection (required), and filter (optional).

  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 (optional, defaults to count all documents)',
      },
    },
    required: ['collection'],
  },