mongodb-atlas-mcp

MatheusNattan365/mongodb-atlas-mcp

3.2

If you are the rightful owner of mongodb-atlas-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A production-ready Model Context Protocol (MCP) server for MongoDB Atlas integration with AI tools like Cursor and Claude Desktop.

Tools
4
Resources
0
Prompts
0

MongoDB Atlas MCP Server

🇺🇸 English | 🇧🇷 Português

English

A production-ready Model Context Protocol (MCP) server for MongoDB Atlas integration with AI tools like Cursor and Claude Desktop. Built with TypeScript, featuring comprehensive database operations, vector search capabilities, and enterprise-grade backup/restore functionality.

🚀 Features

  • Comprehensive Database Operations: Complete CRUD operations with MongoDB Atlas
  • Vector Search Integration: Full Atlas Search vector index management
  • Enterprise Backup/Restore: Production-ready backup and recovery tools
  • Security First: Read-only mode by default, input validation with Zod
  • Docker Ready: Complete containerization with docker-compose
  • Development Friendly: TypeScript, structured logging, graceful shutdown

📊 Supported Operations

Read Operations (Always Available)
  • Database Management: listDatabases, listCollections
  • Document Operations: findDocuments, aggregate
  • Data Export: exportCollection, exportDatabase
  • Backup Operations: backupCollection, backupDatabase
  • Vector Search: listVectorIndexes, getVectorIndexStats
Write Operations (Disabled in READ_ONLY mode)
  • Collection Management: createCollection, deleteCollection
  • Document Operations: insertOne, updateOne, updateMany, deleteOne, deleteMany
  • Batch Operations: bulkWrite
  • Vector Index Management: createVectorIndex, deleteVectorIndex
  • Restore Operations: restoreCollection, restoreDatabase

🏗️ Project Structure

mongodb-atlas-mcp/
├── docker-compose.yml          # Docker orchestration
├── Dockerfile                  # Container configuration
├── package.json               # Node.js dependencies
├── tsconfig.json              # TypeScript configuration
├── .gitignore                 # Git ignore rules
├── src/                       # Source code
│   ├── index.ts              # MCP server entry point
│   ├── tools.ts              # MongoDB tool implementations
│   ├── mongo.ts              # MongoDB client wrapper
│   ├── env.ts                # Environment validation
│   └── logger.ts             # Structured logging
├── scripts/                   # Execution scripts
│   ├── mcp.sh               # Unix wrapper script
│   └── mcp.cmd              # Windows wrapper script
└── mcp.config.example.json   # Cursor configuration example

⚡ Quick Start

  1. Clone and Configure

    git clone <repository-url>
cd mongodb-atlas-mcp

  2. Set Environment Variables Create a .env file:

    MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/?retryWrites=true&w=majority
READ_ONLY=true

  3. Run with Docker (Recommended)

    docker compose up -d --build

  4. Configure Cursor Add to Cursor settings JSON:

    {
  "mcpServers": {
    "MongoDBAtlas": {
      "command": "cmd",
      "args": ["/c", "cd /d /path/to/mongodb-atlas-mcp && scripts\\mcp.cmd"],
      "env": {
        "MONGODB_URI": "your-connection-string",
        "READ_ONLY": "true"
      }
    }
  }
}

  5. Development Mode

    npm install
npm run dev

💾 Backup vs Export

Export Tools (Data Analysis)
  • exportCollection: Export documents in JSON/BSON format
  • exportDatabase: Export schema and metadata for documentation
Backup Tools (Complete Backup)
  • backupCollection: Comprehensive restore-ready backups with chunked processing
  • backupDatabase: Full database backup with collections, indexes, and metadata
Restore Tools (Complete Recovery)
  • restoreCollection: Restore collections with verification
  • restoreDatabase: Selective database restoration

🔍 Vector Search Features

  • Plan-aware Limits: Automatic Atlas plan constraint validation
  • Complete Management: Create, list, delete, and monitor vector indexes
  • Flexible Configuration: Multiple similarity functions and filter fields
  • Status Monitoring: Real-time index status and build progress
Vector Index Limits by Plan:
  • M0/M2/M5 (Free/Shared): 3 search indexes total
  • M10+ (Dedicated): 10 search indexes per collection
  • Atlas Dedicated: Higher limits available

🔒 Security Best Practices

  • Keep READ_ONLY=true unless write operations are required
  • Create dedicated Atlas database users with minimal permissions
  • Use IP allowlists or VPC peering in Atlas
  • Rotate credentials regularly and never commit .env files

🔧 Troubleshooting

MCP not appearing in Cursor?

  • Verify script path and execution permissions
  • On Windows, run git config core.autocrlf input and re-clone to avoid CRLF issues

Need to expose ports?

  • No. MCP via stdio uses process pipes - scripts use docker compose exec -T

Can I connect to local MongoDB?

  • Yes, just adjust the MONGODB_URI accordingly

Português

Um servidor Model Context Protocol (MCP) pronto para produção para integração do MongoDB Atlas com ferramentas de IA como Cursor e Claude Desktop. Construído com TypeScript, com operações abrangentes de banco de dados, recursos de busca vetorial e funcionalidade de backup/restore de nível empresarial.

🚀 Recursos

  • Operações Completas de Banco de Dados: Operações CRUD completas com MongoDB Atlas
  • Integração de Busca Vetorial: Gerenciamento completo de índices vetoriais do Atlas Search
  • Backup/Restore Empresarial: Ferramentas de backup e recuperação prontas para produção
  • Segurança em Primeiro Lugar: Modo somente leitura por padrão, validação de entrada com Zod
  • Pronto para Docker: Containerização completa com docker-compose
  • Amigável ao Desenvolvimento: TypeScript, logging estruturado, desligamento gracioso

📊 Operações Suportadas

Operações de Leitura (Sempre Disponíveis)
  • Gerenciamento de Banco: listDatabases, listCollections
  • Operações de Documento: findDocuments, aggregate
  • Exportação de Dados: exportCollection, exportDatabase
  • Operações de Backup: backupCollection, backupDatabase
  • Busca Vetorial: listVectorIndexes, getVectorIndexStats
Operações de Escrita (Desabilitadas no modo READ_ONLY)
  • Gerenciamento de Coleção: createCollection, deleteCollection
  • Operações de Documento: insertOne, updateOne, updateMany, deleteOne, deleteMany
  • Operações em Lote: bulkWrite
  • Gerenciamento de Índice Vetorial: createVectorIndex, deleteVectorIndex
  • Operações de Restore: restoreCollection, restoreDatabase

⚡ Início Rápido

  1. Clonar e Configurar

    git clone <url-do-repositorio>
cd mongodb-atlas-mcp

  2. Definir Variáveis de Ambiente Criar arquivo .env:

    MONGODB_URI=mongodb+srv://usuario:senha@cluster.mongodb.net/?retryWrites=true&w=majority
READ_ONLY=true

  3. Executar com Docker (Recomendado)

    docker compose up -d --build

  4. Configurar Cursor Adicionar ao JSON de configurações do Cursor:

    {
  "mcpServers": {
    "MongoDBAtlas": {
      "command": "cmd",
      "args": ["/c", "cd /d /caminho/para/mongodb-atlas-mcp && scripts\\mcp.cmd"],
      "env": {
        "MONGODB_URI": "sua-string-de-conexao",
        "READ_ONLY": "true"
      }
    }
  }
}

💾 Backup vs Exportação

Ferramentas de Exportação (Análise de Dados)
  • exportCollection: Exportar documentos em formato JSON/BSON
  • exportDatabase: Exportar esquema e metadados para documentação
Ferramentas de Backup (Backup Completo)
  • backupCollection: Backups abrangentes prontos para restore com processamento em chunks
  • backupDatabase: Backup completo do banco com coleções, índices e metadados
Ferramentas de Restore (Recuperação Completa)
  • restoreCollection: Restaurar coleções com verificação
  • restoreDatabase: Restauração seletiva de banco de dados

🔍 Recursos de Busca Vetorial

  • Limites Conscientes do Plano: Validação automática de restrições do plano Atlas
  • Gerenciamento Completo: Criar, listar, excluir e monitorar índices vetoriais
  • Configuração Flexível: Múltiplas funções de similaridade e campos de filtro
  • Monitoramento de Status: Status de índice em tempo real e progresso de construção
Limites de Índice Vetorial por Plano:
  • M0/M2/M5 (Gratuito/Compartilhado): 3 índices de busca no total
  • M10+ (Dedicado): 10 índices de busca por coleção
  • Atlas Dedicado: Limites mais altos disponíveis

🔒 Melhores Práticas de Segurança

  • Mantenha READ_ONLY=true a menos que operações de escrita sejam necessárias
  • Crie usuários dedicados do banco Atlas com permissões mínimas
  • Use listas de permissão de IP ou VPC peering no Atlas
  • Faça rotação de credenciais regularmente e nunca comite arquivos .env

🔧 Solução de Problemas

MCP não aparece no Cursor?

  • Verifique o caminho do script e permissões de execução
  • No Windows, execute git config core.autocrlf input e re-clone para evitar problemas de CRLF

Preciso expor portas?

  • Não. MCP via stdio usa pipes de processo - scripts usam docker compose exec -T

Posso conectar ao MongoDB local?

  • Sim, apenas ajuste o MONGODB_URI adequadamente

🤝 Contributing | Contribuindo

Contributions are welcome! Please feel free to submit a Pull Request.

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

📄 License | Licença

This project is licensed under the MIT License.

Este projeto está licenciado sob a Licença MIT.