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 | 컬렉션에서 기존 인덱스 삭제 |
고급 사용법
사용자 정의 도구 추가
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
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 파일을 참조하세요.