MongoDB MCP 서버

MongoDB 데이터베이스와의 원활한 상호작용을 표준화된 프로토콜로 제공하는 강력한 Model Context Protocol(MCP) 서버 구현체입니다.

작성자

Rastalion

개요

이 MCP 서버 구현체는 Model Context Protocol을 통해 MongoDB 데이터베이스와 상호작용할 수 있는 강력한 인터페이스를 제공합니다. 데이터베이스, 컬렉션 및 문서에 대한 작업을 async/await 패턴과 오류 처리를 통해 안정적으로 지원합니다.

특징

• MongoDB CRUD 작업 완벽 지원
• MongoDB와의 안전한 연결 처리
• 최적의 성능을 위한 비동기(async/await) 패턴
• 포괄적인 오류 처리
• 쉬운 배포를 위한 Docker 지원
• 타입 힌트를 갖춘 쿼리 실행
• 실시간 업데이트를 위한 SSE(Server-Sent Events) 지원

빠른 시작

CLI 도구로 사용

# 저장소 복제
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

UVX를 통해 실행

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

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

Python 직접 실행

# 저장소 복제
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

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

UVX 사용

UVX는 다양한 환경에서 서비스를 쉽게 관리할 수 있는 도구입니다.

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

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

# 서비스 시작
uvx start mongo-mcp

# 상태 확인
uvx status mongo-mcp

# 로그 확인
uvx logs mongo-mcp

더 자세한 내용은 UVX 가이드를 참조하세요.

환경 변수

서버 실행 전에 다음 환경 변수를 설정하세요:

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

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

API 엔드포인트

• 상태 확인: GET /health
• MCP API: GET /mcp - FastMCP 엔드포인트 (OpenAPI 문서)
• SSE 연결: GET /sse - Server-Sent Events 엔드포인트
• 메시지 처리: POST /messages - 메시지 처리 엔드포인트

IDE 통합

VS Code 설정

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 또는 다른 AI 어시스턴트

Claude 또는 다른 AI 어시스턴트를 위해 MCP 서버를 다음과 같이 구성하세요:

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

사용 가능한 도구

고급 사용법

사용자 정의 도구 추가

1. app/tools/documents/ 또는 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

2. app/tools/registry.py에 도구 등록:

from .documents.my_new_tool import MyNewTool

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

CLI 도구 설치 및 배포

PyPI에 패키지로 등록하여 전역적으로 사용할 수 있습니다:

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

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

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

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

문제 해결

• 서버가 시작되지 않는 경우: mongo-mcp-server --help로 도움말 확인
• MongoDB 연결 문제: --mongodb-url 파라미터가 올바른지 확인
• 도구 실행 오류: 도구 구현과 입력 매개변수 확인
• Docker 문제: docker-compose logs mongo-mcp로 로그 확인

Docker 구성

Docker 설정에는 다음이 포함됩니다:

• Python 3.12 기본 이미지
• Asia/Seoul 타임존
• MongoDB 4.4 인스턴스
• 데이터베이스 스토리지를 위한 영구 볼륨
• 양쪽 서비스에 대한 헬스 체크
• 자동화된 네트워크 구성

라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.