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"
      }
    }
  }
}

사용 가능한 도구

도구 이름	설명
listCollections	데이터베이스의 모든 사용 가능한 컬렉션 목록 조회
find	MongoDB 쿼리 구문을 사용하여 컬렉션의 문서 조회
insertOne	컬렉션에 단일 문서 삽입
updateOne	컬렉션에서 단일 문서 업데이트
deleteOne	컬렉션에서 단일 문서 삭제
indexes	컬렉션의 모든 인덱스 목록 조회
createIndex	컬렉션에 새로운 인덱스 생성
dropIndex	컬렉션에서 기존 인덱스 삭제

고급 사용법

사용자 정의 도구 추가

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 파일을 참조하세요.