MongoDB MCP Server

A powerful Model Context Protocol (MCP) server implementation that provides seamless interaction with MongoDB databases over a standardized protocol.

Author

Rastalion

outline

This MCP server implementation provides a powerful interface to interact with a MongoDB database via the Model Context Protocol. It reliably supports operations on the database, collections, and documents via the async/await pattern and error handling.

characteristic

Full support for MongoDB CRUD operations
Handling secure connections to MongoDB
Async/await pattern for optimal performance
Comprehensive error handling
Docker support for easy deployment
Executing queries with type hints
Support for Server-Sent Events (SSE) for real-time updates

Quick Start

Use as a CLI tool

# 저장소 복제
git clone https://github.com/yourusername/mongo-mcp-server.git
cd mongo-mcp-server

# 개발 모드로 설치
pip install -e .

# 로컬에서 CLI 명령으로 실행
mongo-mcp-server

# SSE 트랜스포트로 실행
mongo-mcp-server --transport=sse

# MongoDB URL 지정
mongo-mcp-server --mongodb-url="mongodb://username:password@hostname:port/dbname"

# 도움말 보기
mongo-mcp-server --help

Run via UVX

# UVX가 설치된 경우
uvx mongo-mcp-server

# SSE 트랜스포트 모드
uvx mongo-mcp-server --transport=sse

Run Python directly

# 저장소 복제
git clone https://github.com/yourusername/mongo-mcp-server.git
cd mongo-mcp-server

# 의존성 설치
pip install -r requirements.txt

# 환경 변수 설정
export MONGODB_URL="mongodb://username:password@hostname:port/dbname?authSource=admin"

# 서버 실행
uvicorn app.main:app --host 0.0.0.0 --port 3000

Using Docker

# 저장소 복제
git clone https://github.com/yourusername/mongo-mcp-server.git
cd mongo-mcp-server

# Docker Compose로 빌드 및 실행
docker-compose up -d

# 로그 확인
docker-compose logs -f mongo-mcp

Using UVX

UVX is a tool that allows you to easily manage services in various environments.

# 등록 스크립트에 실행 권한 부여
chmod +x uvx-register.sh

# UVX에 서비스 등록
./uvx-register.sh

# 서비스 시작
uvx start mongo-mcp

# 상태 확인
uvx status mongo-mcp

# 로그 확인
uvx logs mongo-mcp

For more information, see the UVX Guide .

Environment variables

Before running the server, set the following environment variables:

# 필수
MONGODB_URL="mongodb://username:password@hostname:port/dbname?authSource=admin"

# 선택 - 기본값 표시
PORT=3000
MCP_TRANSPORT=http  # 'http' 또는 'sse'

API endpoint

Check health : GET /health
MCP API : GET /mcp - FastMCP endpoint (OpenAPI documentation)
SSE Connection : GET /sse - Server-Sent Events Endpoint
Message Processing : POST /messages - Message Processing Endpoint

IDE Integration

VS Code Settings

Add the following to your VS Code settings.json:

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "mongodbUri",
        "description": "MongoDB 연결 URI"
      }
    ],
    "servers": {
      "mongodb": {
        "command": "mongo-mcp-server",
        "args": ["--mongodb-url", "$(mongodbUri)"],
        "env": {}
      }
    }
  }
}

Claude or other AI assistant

Configure your MCP server for Claude or other AI assistants as follows:

{
  "mcp": {
    "servers": {
      "mongodb": {
        "url": "http://localhost:3000/mcp"
      }
    }
  }
}

Tools available

Tool name	explanation
`listCollections`	List all available collections in the database
`find`	Retrieving documents in a collection using MongoDB query syntax
`insertOne`	Insert a single document into a collection
`updateOne`	Update a single document in a collection
`deleteOne`	Delete a single document from a collection
`indexes`	List all indexes in a collection
`createIndex`	Create a new index in a collection
`dropIndex`	Delete an existing index from a collection

Advanced Usage

Add custom tools

Create a new tool in app/tools/documents/ or app/tools/collection/ :

from ..base.tool import BaseTool

class MyNewTool(BaseTool):
    @property
    def name(self) -> str:
        return "my_new_tool"

    @property
    def description(self) -> str:
        return "새 도구에 대한 설명"

    @property
    def input_schema(self) -> Dict[str, Any]:
        return {
            "type": "object",
            "properties": {
                # 도구 입력 스키마 정의
            }
        }

    async def execute(self, params: Dict[str, Any]) -> Dict[str, Any]:
        # 도구 실행 로직 구현
        pass

from .documents.my_new_tool import MyNewTool

# ToolRegistry.__init__ 메서드 내에서
self.register_tool(MyNewTool())

Installing and Deploying CLI Tools

You can make it available globally by registering it as a package on PyPI:

# setup.py 확인 후 빌드
python setup.py sdist bdist_wheel

# 패키지 업로드 (PyPI 계정 필요)
twine upload dist/*

# 전역 설치
pip install mongodb-mcp-bridge

# 어디서든 실행 가능
mongodb-mcp-bridge

Troubleshooting

If the server does not start : Check help with mongo-mcp-server --help
MongoDB connection issue : Verify that --mongodb-url parameter is correct
Tool execution error : Check tool implementation and input parameters
Docker issue : Check logs with docker-compose logs mongo-mcp

Docker configuration

Docker configuration includes:

Python 3.12 base image
Asia/Seoul Time Zone
MongoDB 4.4 instance
Persistent volumes for database storage
Health check for both services
Automated network configuration

License

This project is distributed under the MIT License - see the LICENSE file for details.

MongoDB MCP Server

Integrations