hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Integrations

Enables LLMs to interact directly with MongoDB databases, allowing querying collections, inspecting schemas, and managing data through natural language interfaces.

🗄️ LLMS용 MongoDB MCP 서버

LLM이 MongoDB 데이터베이스와 직접 상호 작용할 수 있도록 하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 자연어를 통해 컬렉션을 쿼리하고, 스키마를 검사하고, 데이터를 원활하게 관리할 수 있습니다.

📚 모델 컨텍스트 프로토콜(MCP)이란 무엇인가요?

모델 컨텍스트 프로토콜(MCP)은 Anthropic에서 개발한 개방형 표준으로, AI 시스템이 외부 데이터 소스 및 도구와 연결할 수 있는 보편적인 방법을 제공합니다. MCP는 다음 간의 표준화된 통신 채널을 구축합니다.

MCP 클라이언트 : 데이터를 사용하는 Claude와 같은 AI 어시스턴트(예: Claude Desktop, Cursor.ai)
MCP 서버 : 데이터와 기능을 노출하는 서비스(예: MongoDB 서버)

MCP의 주요 이점:

Universal Access : AI 어시스턴트가 다양한 소스에서 데이터를 쿼리할 수 있는 단일 프로토콜을 제공합니다.
표준화된 연결 : 인증, 사용 정책 및 데이터 형식을 일관되게 처리합니다.
지속 가능한 생태계 : 여러 LLM 클라이언트에서 작동하는 재사용 가능한 커넥터를 촉진합니다.

✨ 특징

🔍 컬렉션 스키마 검사
📊 문서 쿼리 및 필터링
📈 인덱스 관리
📝 문서 작업(삽입, 업데이트, 삭제)
🔒 연결 문자열을 통한 안전한 데이터베이스 액세스
📋 포괄적인 오류 처리 및 검증

📋 필수 조건

시작하기 전에 다음 사항을 확인하세요.

Node.js (v18 이상)
MongoDB 인스턴스(로컬 또는 원격)
Claude Desktop 이나 Cursor.ai 와 같은 MCP 클라이언트

다음을 실행하여 Node.js 설치를 확인할 수 있습니다.

지엑스피1

🚀 빠른 시작

시작하려면 MongoDB 연결 URL을 찾아 Claude Desktop 구성 파일에 다음 구성을 추가하세요.

MacOS : ~/Library/Application\ Support/Claude/claude_desktop_config.json
윈도우 : %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "mongo-mcp",
        "mongodb://<username>:<password>@<host>:<port>/<database>?authSource=admin"
      ]
    }
  }
}

Smithery를 통해 설치

Smithery.ai 는 MCP 서버용 레지스트리 플랫폼으로, 검색 및 설치를 간소화합니다. Smithery를 통해 Claude Desktop용 MongoDB MCP 서버를 자동으로 설치하려면 다음 단계를 따르세요.

npx -y @smithery/cli install mongo-mcp --client claude

Cursor.ai 통합

Cursor.ai와 함께 MongoDB MCP를 사용하려면:

Cursor.ai를 열고 설정 > 기능으로 이동합니다.
기능 패널에서 "MCP 서버"를 찾으세요.
다음 구성으로 새로운 MCP 서버를 추가합니다.
- 이름 : mongodb
- 명령어 : npx
- 인수 : mongo-mcp mongodb://<username>:<password>@<host>:<port>/<database>?authSource=admin

참고: 커서는 현재 Composer 기능의 에이전트에서만 MCP 도구를 지원합니다.

테스트 샌드박스 설정

연결할 MongoDB 서버가 없고 샘플 샌드박스를 만들려면 다음 단계를 따르세요.

Docker Compose를 사용하여 MongoDB를 시작합니다.

docker-compose up -d

테스트 데이터로 데이터베이스를 시드합니다.

npm run seed

Claude Desktop 구성

Claude Desktop 구성 파일에 다음 구성을 추가하세요.

MacOS : ~/Library/Application\ Support/Claude/claude_desktop_config.json
윈도우 : %APPDATA%/Claude/claude_desktop_config.json

로컬 개발 모드:

{
  "mcpServers": {
    "mongodb": {
      "command": "node",
      "args": [
        "dist/index.js",
        "mongodb://root:example@localhost:27017/test?authSource=admin"
      ]
    }
  }
}

테스트 샌드박스 데이터 구조

시드 스크립트는 샘플 데이터를 사용하여 세 개의 컬렉션을 생성합니다.

사용자

개인 정보(이름, 이메일, 나이)
좌표가 포함된 중첩 주소
관심의 배열
회원 가입 날짜

제품

제품 세부 정보(이름, SKU, 카테고리)
중첩된 사양
가격 및 재고 정보
태그 및 평가

명령

품목별 주문 세부 정보
사용자 참조
배송 및 결제 정보
상태 추적

🎯 예시 프롬프트

Claude와 함께 다음 프롬프트를 시도하여 기능을 살펴보세요.

기본 작업

"What collections are available in the database?"
"Show me the schema for the users collection"
"Find all users in San Francisco"

고급 쿼리

"Find all electronics products that are in stock and cost less than $1000"
"Show me all orders from the user john@example.com"
"List the products with ratings above 4.5"

인덱스 관리

"What indexes exist on the users collection?"
"Create an index on the products collection for the 'category' field"
"List all indexes across all collections"

문서 작업

"Insert a new product with name 'Gaming Laptop' in the products collection"
"Update the status of order with ID X to 'shipped'"
"Find and delete all products that are out of stock"

📝 사용 가능한 도구

서버는 데이터베이스 상호작용을 위해 다음과 같은 도구를 제공합니다.

쿼리 도구

listCollections : 데이터베이스에서 사용 가능한 컬렉션을 나열합니다.
find : 필터링 및 프로젝션을 사용하여 문서를 쿼리합니다.
insertOne : 컬렉션에 단일 문서를 삽입합니다.
updateOne : 컬렉션의 단일 문서를 업데이트합니다.
deleteOne : 컬렉션에서 단일 문서를 삭제합니다.

인덱스 도구

createIndex : 컬렉션에 새 인덱스를 생성합니다.
dropIndex : 컬렉션에서 인덱스를 제거합니다.
indexes : 컬렉션의 인덱스를 나열합니다.

🛠️ 개발

이 프로젝트는 다음으로 구성되었습니다.

타입 안전한 개발을 위한 TypeScript
데이터베이스 작업을 위한 MongoDB Node.js 드라이버
스키마 검증을 위한 Zod
서버 구현을 위한 모델 컨텍스트 프로토콜 SDK

개발 환경을 설정하려면:

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

🔒 보안 고려 사항

이 MCP 서버를 MongoDB 데이터베이스와 함께 사용하는 경우:

사용 사례에 필요한 최소한의 권한으로 전담 MongoDB 사용자를 만듭니다.
프로덕션 환경에서는 관리자 자격 증명을 사용하지 마십시오.
감사 목적으로 액세스 로깅을 활성화합니다.
컬렉션에 적절한 읽기/쓰기 권한 설정
연결 문자열 매개변수를 사용하여 액세스를 제한합니다(예: readPreference=secondary ).
데이터베이스 액세스를 제한하기 위해 IP 허용 목록을 고려하세요.

⚠️ 중요 : 데이터베이스 액세스를 구성할 때는 항상 최소 권한 원칙을 따르세요.

🌐 작동 원리

MongoDB MCP 서버:

제공된 연결 문자열을 사용하여 MongoDB 데이터베이스에 연결합니다.
MCP 사양을 따르는 도구로 MongoDB 작업을 노출합니다.
Zod를 사용하여 유형 안전 및 보안을 위해 입력을 검증합니다.
쿼리를 실행하고 LLM 클라이언트에 구조화된 데이터를 반환합니다.
연결 풀링 및 적절한 오류 처리를 관리합니다.

모든 작업은 주입 공격 등의 보안 문제를 방지하기 위해 적절한 검증을 거쳐 실행됩니다.

📦 배포

이 MCP 서버는 여러 가지 방법으로 배포할 수 있습니다.

npx를 통한 로컬(빠른 시작에 표시된 대로)
글로벌 npm 패키지로: npm install -g @coderay/mongo-mcp-server
Docker 컨테이너에서(저장소의 Dockerfile 참조)
Heroku, Vercel 또는 AWS와 같은 플랫폼의 서비스로서

❓ 문제 해결

일반적인 문제

연결 오류
- MongoDB 연결 문자열이 올바른지 확인하세요
- MongoDB 서버가 실행 중이고 액세스 가능한지 확인하세요.
- 네트워크 권한이 연결을 허용하는지 확인하세요.
인증 문제
- 사용자 이름과 비밀번호가 올바른지 확인하세요
- 인증 데이터베이스가 지정되었는지 확인하세요(일반적으로 authSource=admin )
- MongoDB에 TLS/SSL 연결이 필요한지 확인하세요
도구 실행 문제
- Claude Desktop 또는 Cursor.ai를 완전히 다시 시작하세요.
- 자세한 오류 메시지는 로그에서 확인하세요.
  # macOS tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
성능 문제
- 자주 쿼리되는 필드에 적절한 인덱스를 추가하는 것을 고려하세요.
- 쿼리에서 반환되는 데이터를 제한하려면 프로젝션을 사용하세요.
- 페이지 매김에 제한 및 건너뛰기 매개변수 사용

도움 받기

문제가 발생하는 경우:

MCP 문서 검토
GitHub 저장소 에 문제를 제출하세요

🤝 기여하기

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

저장소를 포크하세요
기능 브랜치를 생성합니다( git checkout -b feature/amazing-feature )
변경 사항을 커밋하세요( git commit -m 'Add some amazing feature' )
브랜치에 푸시( git push origin feature/amazing-feature )
풀 리퀘스트 열기

📜 라이센스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested

Claude와 같은 LLM이 MongoDB 데이터베이스와 상호 작용할 수 있도록 하는 프로토콜 서버로, Cursor에서 자연어를 통해 스키마 탐색, 집계 쿼리, 데이터 분석을 위한 도구를 제공합니다.

Related Resources

Reddit Discussion about this server

MongoDB MCP Server