/ 디렉터리 / 플레이그라운드 / MongoDB
● 공식 mongodb-js 🔑 본인 키 필요

MongoDB

제작: mongodb-js · mongodb-js/mongodb-mcp-server

Claude가 MongoDB Atlas 또는 자체 호스팅 클러스터를 쿼리, 집계 및 관리하도록 하세요. 읽기 전용 기본값으로 도구별로 완화할 수 있습니다.

MongoDB의 공식 MCP는 드라이버(모든 클러스터에서의 CRUD + 집계)와 Atlas 제어 평면(프로젝트, 클러스터, 사용자 나열)을 모두 다룹니다. 기본적으로 읽기 전용 모드로 실행되며, 필요할 때 명령 계열별로 쓰기를 명시적으로 활성화할 수 있습니다.

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

mongodb.replay ▶ 준비됨
0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "mongodb",
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json
{
  "context_servers": {
    "mongodb": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mongodb-mcp-server"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add mongodb -- npx -y mongodb-mcp-server

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: MongoDB

MongoDB 집계 파이프라인으로 비즈니스 질문에 답하기

👤 MongoDB 기반 제품의 PM 및 분석가 ⏱ ~15 min beginner

언제 쓸까: 개수, 퍼널 또는 상위 N개 목록이 필요하고 $group/$lookup 구문을 배우고 싶지 않을 때

사전 조건
  • 읽기 전용 연결 문자열 — Atlas: readAnyDatabase를 사용하여 DB 사용자 생성. 자체 호스팅: 관련 DB에 대한 read 역할이 있는 사용자.
흐름
  1. 컬렉션 발견
    데이터베이스를 나열한 다음, app_prod에 대해 모든 컬렉션과 대략적인 문서 개수를 나열하세요.✓ 복사됨
    → 컬렉션 카탈로그
  2. 샘플 및 스키마 추론
    usersorders에서 20개 문서를 샘플링하세요. 보이는 필드와 타입을 설명하세요.✓ 복사됨
    → 컬렉션별 스키마 설명
  3. 실제 집계 실행
    지난 30일 동안 국가별로 몇 개의 주문이 배치되었습니까? 내림차순으로 정렬하고 20으로 제한하세요.✓ 복사됨
    → 사용된 파이프라인이 있는 결과 테이블

결과: 재실행을 위해 정확한 파이프라인이 보존된 비즈니스 답변.

함정
  • 인덱스 없는 집계는 거대한 컬렉션을 스캔할 수 있습니다 — 먼저 항상 .explain()을 확인하고 지원 인덱스가 있는지 확인하세요. 그렇지 않으면 파이프라인 상단의 인덱싱된 필드에 좁게 $match를 추가하세요
함께 쓰기: notion

지저분한 컬렉션의 실제 스키마 추론 및 문서화

👤 문서화되지 않은 MongoDB로 온보딩되는 신입 엔지니어 ⏱ ~25 min intermediate

언제 쓸까: 컬렉션이 3년 동안 '스키마 없이' 있었고 어떤 필드가 실제로 존재하는지 아무도 모를 때

흐름
  1. 광범위하게 샘플링
    events에서 500개 문서를 샘플링하세요. 각 최상위 필드에 대해 존재 %, 타입 및 샘플 값을 보고하세요.✓ 복사됨
    → 필드별 존재/타입 매트릭스
  2. 스키마 드리프트 찾기
    어떤 필드가 문서 전반에 걸쳐 여러 타입을 가지고 있습니까? (필드, 타입)별로 그룹화하고 개수를 세세요.✓ 복사됨
    → 다형성 필드 목록
  3. TypeScript 타입 또는 JSON 스키마 생성
    '안정적인' 필드(≥95% 존재, 단일 타입)에 대한 TypeScript 인터페이스를 생성하세요. 나머지는 선택적 또는 알 수 없음으로 표시하세요.✓ 복사됨
    → 사용 가능한 타입 정의

결과: 알려진 특이점이 있는 문서화된 스키마 — 마이그레이션 또는 유효성 검사자의 기초.

함정
  • 500개 문서는 드물지만 중요한 변형을 놓칠 수 있습니다 — 레거시 형태를 포착하기 위해 시간 버킷(월 1개)별로 샘플링하세요
함께 쓰기: filesystem

보안 및 비용을 위해 Atlas 프로젝트 감사

👤 Atlas의 DevOps/플랫폼 팀 ⏱ ~20 min intermediate

언제 쓸까: 분기별: 어떤 클러스터가 과도하게 크기 조정되었는지, 어떤 클러스터가 광범위한 IP 허용 목록을 가지고 있는지, 누가 액세스 권한을 가지고 있는지 확인하세요.

사전 조건
  • Atlas API 공개+개인 키 — cloud.mongodb.com → Organization Access → API keys; 프로젝트 범위
흐름
  1. 프로젝트 + 클러스터 나열
    모든 프로젝트와 각 프로젝트 내의 모든 클러스터를 해당 계층, 지역 및 백업 상태와 함께 나열하세요.✓ 복사됨
    → 전체 인벤토리
  2. 위험한 액세스 플래그
    각 프로젝트에 대해 IP 액세스 목록을 덤프하세요. 프로젝트 이름으로 0.0.0.0/0의 모든 항목을 플래그하세요.✓ 복사됨
    → 위험한 액세스 보고서
  3. 적절한 크기 조정 제안
    10GB 미만 사용한 M30+ 클러스터가 있습니까? 다운그레이드를 권장합니다.✓ 복사됨
    → 비용 절감 목록

결과: 보안 및 재무 담당자를 위한 짧은 수정 목록.

함정
  • 모든 프로젝트를 보기에는 API 키 범위가 너무 좁습니다 — 프로젝트 수준의 키 대신 조직 수준의 키를 읽기 전용 모드로 사용하세요
함께 쓰기: notion

일회성 데이터 정리를 안전하게 제안하고 실행하기

👤 데이터 버그를 수정하는 백엔드 엔지니어 ⏱ ~30 min advanced

언제 쓸까: 버그로 인해 잘못된 쓰기가 발생했습니다. ~10k 문서를 수정해야 하지만 잘못된 문서를 제거하면 안 됩니다.

사전 조건
  • 쓰기 가능 사용자(대상 DB로만 범위 지정) — Atlas: 해당 DB에만 readWrite 역할, 그 외에는 없음
  • 이 세션에서 --read-only를 명시적으로 OFF로 — --read-only 없이 MCP 시작
흐름
  1. 개수로 수정 범위 지정
    status='active' AND last_login IS NULL AND created_at < 2024-01-01users의 문서 개수를 세세요. 아무것도 수정하지 마세요.✓ 복사됨
    → 예상 영향 개수, 예: 9,873
  2. 업데이트 드라이 런
    실행할 updateMany 파이프라인(필터 + $set)을 표시하고, 변경될 5개 샘플 문서를 표시하세요. 실행하지 마세요.✓ 복사됨
    → 필터 + 설정 미리보기
  3. 제한과 함께 실행 및 확인
    업데이트를 실행하세요. 그런 다음 원래 개수를 다시 실행하세요. 0이어야 합니다. matchedCount 및 modifiedCount를 보고하세요.✓ 복사됨
    → 개수가 예상과 일치; 쿼리가 0을 반환하는지 확인

결과: 이전 및 이후 개수가 있는 깔끔하고 감시 가능한 수정.

함정
  • 잘못된 필터를 사용한 updateMany는 전체 컬렉션을 제거합니다 — 항상 먼저 필터를 countDocuments로 실행하세요. 개수가 놀라우면 중단하고 조사하세요
  • 영향받는 슬라이스의 백업이 없습니다 — 업데이트하기 전에 일치하는 문서를 <collection>_backup_<date> 컬렉션에 복사하세요
함께 쓰기: filesystem

느린 쿼리 패턴에서 누락된 인덱스 제안

👤 성능 문제를 찾는 백엔드 엔지니어 ⏱ ~25 min advanced

언제 쓸까: 앱이 MongoDB 쿼리에서 느립니다. 샷건이 아닌 대상 인덱스 계획을 원합니다.

흐름
  1. 기존 인덱스 확인
    ordersusers에 대해 키 및 디스크 크기를 가진 모든 인덱스를 나열하세요.✓ 복사됨
    → 인덱스 카탈로그
  2. 특정 쿼리 프로파일링
    이 쿼리 [붙여넣기]에서 .explain('executionStats')를 실행하세요. totalDocsExamined vs nReturned 및 우승 계획 단계를 보고하세요.✓ 복사됨
    → 설명 출력
  3. 가장 작은 새 인덱스 제안
    그 계획이 주어지면, 이것을 IXSCAN으로 변환할 정확히 하나의 인덱스를 제안하세요. 필드 순서를 정당화하세요.✓ 복사됨
    → 이론적 근거가 있는 구체적인 createIndex 명령

결과: 느린 쿼리당 하나의 정당성이 있는 인덱스 권장 사항 — 그 벽이 아닙니다.

함정
  • 과도한 인덱싱은 쓰기 처리량을 죽이고 스토리지를 부풀립니다 — >1 고트래픽 쿼리를 제공하는 인덱스만 추가하세요. 복합 인덱스는 ESR(동등성, 정렬, 범위) 순서를 반영해야 합니다

조합

다른 MCP와 조합해 10배 효율

mongodb + notion

집계, 그 다음 공유 가능한 보고서 게시

지난 6개월 동안 계획 계층별 MAU를 계산하고 결과를 테이블로 'Growth / Monthly'에 Notion 페이지를 생성하세요.✓ 복사됨
mongodb + filesystem

정리 전에 컬렉션 슬라이스를 JSONL로 백업

users에서 <filter>와 일치하는 모든 문서를 찾아 /backups/users-cleanup-<date>.jsonl에 저장한 다음 삭제하세요.✓ 복사됨
mongodb + postgres

MongoDB에서 마이그레이션할 때 데이터베이스 간 조정

MongoDB users의 모든 user_id에 대해 Postgres users에 해당 행이 존재하는지 확인하세요. 불일치를 보고하세요.✓ 복사됨

도구

이 MCP가 노출하는 것

도구입력언제 호출비용
list_databases 모든 탐색 세션의 시작 free
list_collections database: str 데이터베이스 인벤토리 free
find database, collection, filter?, projection?, sort?, limit? 문서 읽기 — 주요 읽기 워크호스 free
aggregate database, collection, pipeline: stage[] 그룹화, 조인, 분석 free
count database, collection, filter? 항상 파괴적인 쓰기 전에 — 범위 확인 free
insert_one / insert_many database, collection, document(s) --read-only 꺼짐 필요 writes
update_one / update_many database, collection, filter, update 항상 먼저 개수로 필터 미리보기 writes
delete_one / delete_many database, collection, filter 위험 — 명시적 사용자 확인 필요 writes
list_indexes database, collection 새 인덱스를 제안하기 전에 성능 분석 free
atlas_list_projects / atlas_list_clusters Atlas 제어 평면 감사 free

비용 및 제한

운영 비용

API 쿼터
드라이버: 클러스터 연결 제한으로 제한됨. Atlas API: 키당 분당 100개 요청.
호출당 토큰
찾기/집계: 결과 크기에 따라 확장; 프로젝션 및 제한 사용.
금액
기존 클러스터에 대해 무료. Atlas는 테스트를 위해 무료 M0 계층을 가지고 있습니다.
항상 필요한 필드만 프로젝션하세요. 제한 없는 찾기는 컨텍스트와 송신을 사용하는 큰 문서를 반환합니다.

보안

권한, 시크릿, 파급범위

최소 스코프: readAnyDatabase(읽기 전용) 또는 특정 DB에 대한 read
자격 증명 저장: 드라이버의 경우 MDB_MCP_CONNECTION_STRING; Atlas의 경우 MDB_MCP_API_CLIENT_ID + MDB_MCP_API_CLIENT_SECRET
데이터 외부 송신: 드라이버는 클러스터에 연결되고; Atlas API는 cloud.mongodb.com에만 연결됩니다
절대 부여 금지: dbAdminAnyDatabase userAdminAnyDatabase root

문제 해결

자주 발생하는 오류와 해결

MongoServerError: 인증 실패

연결 문자열 사용자/암호가 잘못되었거나 사용자가 auth DB가 없습니다. Atlas의 경우 ?authSource=admin을 추가하세요.

확인: mongosh '$MDB_MCP_CONNECTION_STRING' --eval 'db.runCommand({ping:1})'
MongoNetworkError: ETIMEDOUT

IP가 Atlas 허용 목록에 없습니다. Atlas → Network Access에 현재 IP를 추가하세요.

확인: curl ifconfig.me then compare
listDatabases 명령을 실행하도록 관리자에 대한 권한이 없습니다

역할이 너무 좁습니다. clusterMonitor를 부여하거나 대신 listCollections을 통해 도구를 특정 DB로 범위 지정하세요.

쓰기 거부됨 / 읽기 전용 모드에서 실행 중

--read-only 없이 MCP를 다시 시작하세요. 특정 수정 세션에만 이 작업을 수행하세요.

대안

MongoDB 다른 것과 비교

대안언제 쓰나단점/장점
Postgres MCPPostgres를 사용 중이거나 MongoDB에서 마이그레이션을 고려 중입니다관계형 — 문서 스타일 유연성 사라짐
DBHubMongoDB + 여러 SQL DB에 대해 하나의 MCP가 필요합니다공식 서버보다 얕은 MongoDB 기능 범위

더 보기

리소스

📖 GitHub에서 공식 README 읽기

🐙 열린 이슈 보기

🔍 400+ MCP 서버 및 Skills 전체 보기