MongoDB Memory Server

License: MIT Node.js Version MCP Spec Compliance Tests

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

---

✨ 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

Variable	Default Value	Description
NODE_ENV	development	Environment mode (development, production, test)
TRANSPORT	stdio	MCP Transport mode (stdio or http)
PORT	3000	HTTP port when TRANSPORT=http
MONGODB_URI	mongodb://localhost:27017/agent_memory	MongoDB connection URI
LOG_LEVEL	info	Logging verbosity (error, warn, info, debug)
ENABLE_AUTH	false	Enable/disable authentication middleware
API_KEY	your_admin_api_key_here	Master Admin API key
JWT_SECRET	your_jwt_secret_here	Secret for signing JWT tokens (min 32 chars)

---

🚀 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

Script	Command	Purpose
npm start	node src/server.js	Launch server in Stdio mode
npm run start:http	TRANSPORT=http node src/server.js	Launch server in HTTP network mode
npm test	vitest run	Execute 99 unit & integration tests
npm run lint	eslint .	Execute ESLint code quality checks
npm run format	prettier --write .	Format codebase with Prettier
npm run check-connection	node src/utils/testConnection.js	Execute connection diagnostics
npm run generate-auth	node src/utils/generateAuth.js	CLI helper to generate API keys & JWTs

---

🔌 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