dapapkung/mongo-ts-mcp

MongoDB MCP Server

A Model Context Protocol (MCP) server for MongoDB operations, built with TypeScript.

Features

• 🔌 Connect to multiple MongoDB instances
• 🔍 Query, aggregate, and analyze collections
• 📊 Schema inference and data sampling
• 🚀 Built with TypeScript for type safety
• ⚡ No build step needed - runs directly with tsx

Prerequisites

• Node.js 18+ (recommended: v22.4.1+)
• MongoDB instance(s) to connect to
• Claude Desktop (for MCP integration)

Installation

1. Clone and Install Dependencies

git clone <your-repo-url>
cd mongo-ts-mcp
npm install

2. Configure MongoDB Connections

Create a config.json file in the project root:

cp config.json.example config.json

Edit config.json with your MongoDB connection details:

{
  "connections": {
    "local": {
      "uri": "mongodb://localhost:27017",
      "database": "mydb"
    },
    "production": {
      "uri": "mongodb://user:password@host:27017",
      "database": "prod_db"
    }
  }
}

3. Make start-mcp.sh Executable (Linux/macOS/WSL)

chmod +x start-mcp.sh

Usage

Run Locally (Development)

# Direct execution with tsx (no build needed!)
npm start

# Or with npx
npx tsx src/index.ts

# Watch mode (auto-reload on changes)
npm run watch

Run with Claude Desktop

Add to your Claude Desktop config file:

Location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

Option A: Using start-mcp.sh (Recommended)

{
  "mcpServers": {
    "mongodb": {
      "command": "bash",
      "args": ["/path/to/mongo-ts-mcp/start-mcp.sh"]
    }
  }
}

Option B: Direct npx (Cross-platform)

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "/path/to/mongo-ts-mcp/src/index.ts"
      ],
      "cwd": "/path/to/mongo-ts-mcp"
    }
  }
}

Option C: WSL (Windows Only)

{
  "mcpServers": {
    "mongodb": {
      "command": "wsl",
      "args": [
        "bash",
        "-l",
        "-c",
        "cd /home/user/projects/mongo-ts-mcp && npx tsx src/index.ts 2>/tmp/mcp-mongodb-error.log"
      ]
    }
  }
}

Replace /path/to/mongo-ts-mcp with your actual project path.

Restart Claude Desktop

After updating the config, fully restart Claude Desktop for changes to take effect.

Available Tools

The MCP server provides these tools to Claude:

• list_collections - List all collections in a database
• query_collection - Query documents with filters and sorting
• aggregate - Run MongoDB aggregation pipelines
• count_documents - Count documents matching a filter
• get_schema - Infer schema from collection samples
• sample_data - Get random sample documents
• distinct_values - Get distinct values for a field

Development

Project Structure

mongo-ts-mcp/
├── src/
│   ├── index.ts        # Main entry point
│   ├── connection.ts   # MongoDB connection management
│   ├── tools.ts        # MCP tool implementations
│   └── logger.ts       # Logging utilities
├── config.json         # MongoDB connections (not committed)
├── config.json.example # Example configuration
├── start-mcp.sh        # Shell script for easy startup
├── package.json
├── tsconfig.json
└── README.md

Tech Stack

• Runtime: Node.js with tsx (no build step!)
• Language: TypeScript
• MCP SDK: @modelcontextprotocol/sdk
• Database: MongoDB Node.js Driver
• Module System: ES Modules

Why tsx?

This project uses tsx instead of traditional TypeScript compilation:

✅ No build step - Edit and run directly
✅ Clean imports - No .js extensions needed in TypeScript files
✅ Fast development - Instant reload on changes
✅ Production-ready - Used by many large projects

Building (Optional)

If you need compiled JavaScript for distribution:

npm run build

Output will be in dist/ folder. But for MCP usage, this is not necessary!

Troubleshooting

Error: Cannot find module

Make sure all imports in TypeScript files do NOT have .js extensions:

// ✅ Correct
import { something } from "./module";

// ❌ Wrong (when using tsx)
import { something } from "./module.js";

Check Logs

Linux/macOS/WSL:

# If using error log redirect
cat /tmp/mcp-mongodb-error.log

# Or check Claude Desktop logs
tail -f ~/.config/Claude/logs/mcp*.log

Windows:

# Check Claude Desktop logs
type %APPDATA%\Claude\logs\mcp*.log

Connection Issues

Verify your config.json:

1. MongoDB URI is correct
2. Database name exists
3. Network access is allowed
4. Authentication credentials are valid

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with Claude Desktop
5. Submit a pull request

Support

For issues or questions:

• Open an issue on GitHub
• Check MCP documentation: https://modelcontextprotocol.io

Acknowledgments

Built with the Model Context Protocol by Anthropic.