NestJS MongoDB MCP Server

A NestJS-based Model Context Protocol (MCP) server with Clean Architecture for MongoDB operations. This server allows AI assistants like Claude to interact with MongoDB databases through standardized MCP tools, resources, and prompts.

Features

• Clean Architecture: Full separation of concerns with Domain, Application, Infrastructure, and Presentation layers

• MCP Protocol Support: Complete implementation of MCP with tools, resources, and prompts

• MongoDB Integration: Full CRUD operations and aggregation support

• Dual Transport: STDIO mode for local Claude Desktop integration and HTTP/SSE for remote access

• Structured Logging: Winston-based logging with daily rotation

• Type Safety: Full TypeScript with Zod schema validation

• Testing: Unit, integration, and e2e test setup with Jest

• Docker Support: Docker Compose for local development with MongoDB and Mongo Express

Architecture

Prerequisites

• Node.js 20+

• MongoDB 7.0+

• npm or yarn

Installation

1. Clone the repository:

1. Install dependencies:

1. Create environment file:

1. Configure environment variables in .env:

Running the Application

Development Mode

1. Start MongoDB with Docker Compose:

1. Run in development mode:

Production Mode

Docker Compose (Full Stack)

This will start:

• MongoDB on port 27017

• Mongo Express UI on port 8081 (http://localhost:8081)

• NestJS MCP Server on port 3000

MCP Tools Available

The server exposes the following MCP tools for MongoDB operations:

• mongodb-find: Query documents with filters, projection, sorting, and limits

• mongodb-insert: Insert a single document

• mongodb-insert-many: Insert multiple documents

• mongodb-update-many: Update documents matching a filter

• mongodb-delete-many: Delete documents matching a filter

• mongodb-count: Count documents in a collection

• mongodb-aggregate: Execute aggregation pipelines

MCP Resources Available

• mongodb-collections: List all collections in a database

MCP Prompts Available

• mongodb-query-builder: Help build MongoDB queries from natural language

Integration with Claude Desktop

STDIO Mode (Recommended for Local Use)

1. Build the project:

1. Configure Claude Desktop by editing:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the server configuration:

1. Restart Claude Desktop

2. Verify the connection by asking Claude:

   • "List all collections in my MongoDB database"

   • "Find all documents in the users collection"

HTTP/SSE Mode (For Remote Access)

1. Set environment variables:

1. Start the server:

1. The MCP endpoint will be available at: http://localhost:3000/api/mcp

Testing

Run Unit Tests

Run Integration Tests

Run E2E Tests

Run All Tests with Coverage

Example Usage with Claude

Once integrated with Claude Desktop, you can use natural language commands:

Query Documents:

Insert Document:

Update Documents:

Count Documents:

Aggregate Data:

Project Structure Details

Domain Layer

• Entities: Core business objects (Document, Collection, QueryResult)

• Value Objects: Validated objects (DatabaseName, CollectionName, QueryFilter)

• Repository Interfaces: Abstractions for data access

Application Layer

• Use Cases: Business logic for each operation

• DTOs: Data transfer objects with class-validator decorators

• Services: Application services (e.g., query validation)

Infrastructure Layer

• MongoDB Repository: Concrete implementation of repository interface

• MCP Tools: Decorators-based MCP tool implementations

• Logging: Winston-based structured logging

• Configuration: Environment-based configuration modules

Configuration

Database Configuration

• MONGODB_URI: MongoDB connection string

• MONGODB_DATABASE: Default database name

MCP Configuration

• MCP_TRANSPORT: Transport mode (STDIO or SSE)

• MCP_PORT: Port for SSE mode (default: 3000)

• MCP_READ_ONLY_MODE: Restrict to read-only operations

Logging Configuration

• LOG_LEVEL: Logging level (debug, info, warn, error)

• LOG_DIR: Directory for log files (default: ./logs)

• NODE_ENV: Environment (development, production)

Security Considerations

• Read-Only Mode: Enable with MCP_READ_ONLY_MODE=true to prevent write operations

• Environment Variables: Use environment variables for sensitive configuration

• Validation: All inputs are validated with class-validator and Zod

• Logging: In STDIO mode, logs go to stderr to avoid corrupting JSON-RPC messages

API Endpoints

When running in HTTP/SSE mode:

• GET /health: Health check endpoint

• POST /api/mcp: MCP JSON-RPC endpoint

• GET /api/mcp: SSE endpoint for server-to-client messages

Development

Code Style

Adding New Tools

1. Create use case in src/application/use-cases/

2. Define Zod schema in src/infrastructure/mcp/validators/mongodb-schemas.ts

3. Create tool in src/infrastructure/mcp/tools/

4. Register in src/infrastructure/mcp/mcp.module.ts

Adding New Resources

1. Create resource in src/infrastructure/mcp/resources/

2. Register in src/infrastructure/mcp/mcp.module.ts

Troubleshooting

Claude Desktop Not Connecting

1. Check that the path in claude_desktop_config.json is absolute

2. Verify the project is built: npm run build

3. Check logs in stderr when running in STDIO mode

4. Restart Claude Desktop after configuration changes

MongoDB Connection Issues

1. Verify MongoDB is running: docker-compose ps

2. Check MONGODB_URI in your environment

3. Ensure MongoDB port (27017) is accessible

Tool Execution Errors

1. Check logs in the configured LOG_DIR

2. Verify database and collection names are valid

3. Ensure proper MongoDB permissions

Contributing

1. Fork the repository

2. Create a feature branch

3. Implement your changes with tests

4. Submit a pull request

License

MIT

Support

For issues and questions:

• Create an issue in the repository

• Check the MCP documentation: https://modelcontextprotocol.io

Acknowledgments

• Built with NestJS

• MCP integration using @modelcontextprotocol/sdk

• MongoDB driver: Mongoose

• Logging: Winston

• Validation: Zod and class-validator