MongoDB Memory MCP Server

A production-grade, collaborative MongoDB Memory Model Context Protocol (MCP) Server built using Node.js (ES Modules), MongoDB 7.0, and the official @modelcontextprotocol/sdk.

Acts as a persistent long-term memory engine for AI agents (Claude Desktop, Cursor, Antigravity, Gemini CLI, or custom AI agents), enabling them to store, search, update, delete, retrieve, and summarize structured project memories across developer workflows.

📋 Table of Contents

• Features

• Tech Stack

• Folder Structure

• Prerequisites

• Installation

• Environment Variables

• Running Locally

• Production Build & Docker

• Package Scripts

• API Reference

• Client Configuration

• Troubleshooting

• Security

• Roadmap

• Contributing

• Code Style

• License

• Acknowledgements

Related MCP server: elephantasm-mcp

✨ Features

• 2026-07-28 MCP Specification Compliant: Mandatory server/discover RPC, stateless _meta parsing, "resultType": "complete", ttlMs / cacheScope indicators, Streamable HTTP headers (Mcp-Method, Mcp-Name), and deterministic tool sorting.

• 15 Modular MCP Tools: Standardized CRUD operations, score-weighted full-text search, tag filtering, type filtering, recency listing, project context summarization, and Atlas Vector Search readiness.

• 6 Dynamic Context Resources (memory://): Exposes live readable project context URIs (memory://project/{projectId}, memory://decision/{projectId}, memory://bugs/{projectId}, etc.).

• 6 Reusable AI Prompt Templates: Automated prompt generators for architecture reviews, code reviews, documentation generation, and sprint summaries.

• Developer Onboarding REST APIs: Management endpoints for projects (/api/projects), developers (/api/developers), project-bound API keys (/api/keys), and signed JWT tokens (/api/tokens).

• Dynamic Scope Isolation: Automatically binds req.auth.projectId via MongoDB API key lookup to enforce tenant memory isolation.

• Dual Transport Modes: Local desktop IDEs via Stdio (npm start) and remote network agents via Streamable HTTP (npm run start:http) at http://localhost:3000/messages.

• Auto-Generated Postman Collection: Live downloadable Postman collection v2.1.0 available at GET /postman.json.

• Case-Insensitive Searching: Case-insensitive regex matching ensuring TodoNative, todonative, and TODONATIVE match 100% reliably.

• Comprehensive Test Suite: 99 unit & integration tests passing across 21 test suites (vitest + mongodb-memory-server).

🛠️ Tech Stack

• Runtime: Node.js 20+ LTS (ES Modules)

• MCP SDK: @modelcontextprotocol/sdk (v1.5.0+)

• Database: MongoDB 7.0+ (mongodb Native Node Driver)

• Web Server: Express v4.21.2 & Cors v2.8.5

• Schema Validation: zod v3.24.1

• Security & Auth: jsonwebtoken v9.0.2

• Logger: winston v3.17.0 (Stderr-safe structured JSON logger)

• Testing: vitest v3.0.4 & mongodb-memory-server v10.1.3

• Containerization: Docker & Docker Compose

📂 Folder Structure

mongodb-mcp/
├── docs/                              # Comprehensive documentation suite (11 guides)
├── src/                               # Application source code
│   ├── config/                        # Environment & config validation
│   ├── database/                      # MongoDB connection pool & indexing
│   ├── mcp/                           # MCP 2026-07-28 protocol handlers
│   ├── middleware/                    # Express auth & protocol middleware
│   ├── models/                        # Protocol constants & error hierarchy
│   ├── prompts/                       # MCP Prompt Templates Engine
│   ├── repositories/                  # MongoDB Data Access Repositories
│   ├── resources/                     # MCP Dynamic Resources (`memory://`)
│   ├── schemas/                       # Zod validation schemas
│   ├── services/                      # Core Business Logic Services
│   ├── tools/                         # Modular MCP Tools Registry (15 tools)
│   ├── transports/                    # Transport layer (Express HTTP / SSE)
│   ├── utils/                         # Logger, errors, Postman generator
│   └── server.js                      # Main server entrypoint & bootstrap
├── tests/                             # Vitest Test Suite (99 tests)
│   ├── unit/                          # Unit test files
│   └── integration/                   # Integration test files
├── Dockerfile                         # Multi-stage production Dockerfile
├── docker-compose.yml                 # Docker Compose deployment stack
├── package.json                       # Dependencies & npm scripts
└── README.md                          # Master GitHub README

⚙️ Prerequisites

• Node.js: >=20.0.0 LTS

• npm: >=10.0.0

• MongoDB: 7.0+ (Local instance or Docker container)

📥 Installation

# 1. Clone repository
git clone https://github.com/your-username/mongodb-memory-mcp.git
cd mongodb-memory-mcp

# 2. Install dependencies
npm install

# 3. Create environment configuration
cp .env.example .env

🔑 Environment Variables

🚀 Running Locally

# Start MongoDB via Docker Compose
docker-compose up -d mongodb

# Launch in Stdio Mode (Default for local desktop IDEs)
npm start

# Launch in HTTP Network Mode (Port 3000)
npm run start:http

🐳 Production Build & Docker

# Build & run entire container stack
docker-compose up -d --build

# View container logs
docker-compose logs -f mcp-server

📜 Package Scripts

🔌 Client Configuration

Streamable HTTP Mode (Antigravity, Cursor, VS Code, Gemini CLI)

{
  "mcpServers": {
    "mongodb-memory": {
      "url": "http://localhost:3000/messages",
      "type": "streamable-http",
      "headers": {
        "X-API-Key": "mcp-memory-api-key"
      }
    }
  }
}

Stdio Subprocess Mode (Claude Desktop)

{
  "mcpServers": {
    "mongodb-memory": {
      "command": "node",
      "args": ["/Users/sahil/Projects/mongodb-mcp/src/server.js"],
      "env": {
        "TRANSPORT": "stdio",
        "MONGODB_URI": "mongodb://localhost:27017/agent_memory"
      }
    }
  }
}

📖 API Documentation

Complete API documentation for REST endpoints, MCP tools, resources, and prompt templates is available in docs/API_REFERENCE.md and docs/USER_GUIDE.md.

🛡️ Security Policy

Please review our SECURITY.md for vulnerability reporting guidelines.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md and our CODE_OF_CONDUCT.md for guidance.

📄 License

Distributed under the MIT License. See LICENSE for details.

🙏 Acknowledgements

• Model Context Protocol (MCP) by Anthropic

• MongoDB Native Node Driver

• Express Framework