MongoDB MCP Server

MongoDB 데이터베이스 및 MongoDB Atlas와 상호작용하기 위한 Model Context Protocol 서버입니다.

📚 목차

• 🚀 시작하기

  • 사전 요구 사항

  • 설정

    • 빠른 시작

• 🛠️ 지원되는 도구

  • MongoDB Atlas 도구

  • MongoDB 데이터베이스 도구

• ⚙️ 구성

  • 구성 옵션

  • Atlas API 액세스

  • 구성 방법

    • 환경 변수

    • 명령줄 인수

    • MCP 클라이언트 구성

• 🤝 기여

사전 요구 사항

• Node.js (v20.10.0 이상)

node -v

• MongoDB 연결 문자열 또는 Atlas API 자격 증명, 구성하지 않으면 서버가 시작되지 않습니다.

  • Atlas 도구를 사용하려면 서비스 계정 Atlas API 자격 증명이 필요합니다. MongoDB Atlas에서 서비스 계정을 만들고 해당 자격 증명을 인증에 사용할 수 있습니다. 자세한 내용은 Atlas API 액세스를 참조하세요.

  • MongoDB 연결 문자열이 있으면 이를 사용하여 MongoDB 인스턴스에 직접 연결할 수 있습니다.

설정

빠른 시작

참고: Atlas API 자격 증명을 사용할 때는 서비스 계정에 최소한의 필수 권한만 할당해야 합니다. 자세한 내용은 Atlas API 권한을 참조하세요.

대부분의 MCP 클라이언트는 MCP 서버를 추가하려면 구성 파일을 만들거나 수정해야 합니다.

참고: 구성 파일 구문은 클라이언트마다 다를 수 있습니다. 최신 예상 구문은 다음 링크를 참조하세요:

• Windsurf:https://docs.windsurf.com/windsurf/mcp

• VSCode: https://code.visualstudio.com/docs/copilot/chat/mcp-servers

• Claude Desktop: https://modelcontextprotocol.io/quickstart/user

• Cursor: https://docs.cursor.com/context/model-context-protocol

옵션 1: 연결 문자열 인수

인수를 통해 연결 문자열을 전달할 수 있습니다. 유효한 사용자 이름과 비밀번호를 사용해야 합니다.

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--connectionString",
        "mongodb://localhost:27017/myDatabase"
      ]
    }
  }
}

참고: 연결 문자열은 로컬 인스턴스든 Atlas 클러스터든 모든 MongoDB 클러스터에 연결하도록 구성할 수 있습니다.

옵션 2: Atlas API 자격 증명 인수

Atlas API 서비스 계정 자격 증명을 사용하세요. Atlas API 액세스 섹션의 모든 단계를 따라야 합니다.

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--apiClientId",
        "your-atlas-service-accounts-client-id",
        "--apiClientSecret",
        "your-atlas-service-accounts-client-secret"
      ]
    }
  }
}

옵션 3: 명령 인수를 사용한 독립 실행 서비스

npx 명령을 사용하여 서버 시작:

 npx -y mongodb-mcp-server --apiClientId="your-atlas-service-accounts-client-id" --apiClientSecret="your-atlas-service-accounts-client-secret"

• 전체 인수 목록은 구성 옵션을 참조하세요.

• Atlas 서비스 계정 자격 증명 구성은 Atlas API 액세스를 참조하세요.

옵션 4: 환경 변수를 사용한 독립 실행 서비스

 npx -y mongodb-mcp-server

구성 파일에서 환경 변수를 사용하거나 환경 변수를 설정한 후 npx를 통해 서버를 실행할 수 있습니다.

• MCP 파일의 환경 변수를 통한 연결 문자열 예시

• MCP 파일의 환경 변수를 통한 Atlas API 자격 증명 예시

옵션 5: Docker 사용

Docker 컨테이너에서 MongoDB MCP Server를 실행할 수 있습니다. 이는 격리를 제공하며 로컬 Node.js 설치가 필요하지 않습니다.

환경 변수로 실행

MongoDB 연결 문자열 또는 Atlas API 자격 증명 중 하나를 제공할 수 있습니다:

옵션 A: 구성 없음

docker run --rm -i \
  mongodb/mongodb-mcp-server:latest

옵션 B: MongoDB 연결 문자열 사용

docker run --rm -i \
  -e MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" \
  mongodb/mongodb-mcp-server:latest

옵션 C: Atlas API 자격 증명 사용

docker run --rm -i \
  -e MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id" \
  -e MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret" \
  mongodb/mongodb-mcp-server:latest

MCP 구성 파일의 Docker

옵션 없이:

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "mongodb/mongodb-mcp-server:latest"]
    }
  }
}

연결 문자열 사용:

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MDB_MCP_CONNECTION_STRING=mongodb+srv://username:password@cluster.mongodb.net/myDatabase",
        "mongodb/mongodb-mcp-server:latest"
      ]
    }
  }
}

Atlas API 자격 증명 사용:

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MDB_MCP_API_CLIENT_ID=your-atlas-service-accounts-client-id",
        "-e",
        "MDB_MCP_API_CLIENT_SECRET=your-atlas-service-accounts-client-secret",
        "mongodb/mongodb-mcp-server:latest"
      ]
    }
  }
}

🛠️ 지원되는 도구

도구 목록

MongoDB Atlas 도구

• atlas-list-orgs - MongoDB Atlas 조직 나열

• atlas-list-projects - MongoDB Atlas 프로젝트 나열

• atlas-create-project - 새 MongoDB Atlas 프로젝트 생성

• atlas-list-clusters - MongoDB Atlas 클러스터 나열

• atlas-inspect-cluster - 특정 MongoDB Atlas 클러스터 검사

• atlas-create-free-cluster - 무료 MongoDB Atlas 클러스터 생성

• atlas-connect-cluster - MongoDB Atlas 클러스터에 연결

• atlas-inspect-access-list - MongoDB Atlas 클러스터에 액세스할 수 있는 IP/CIDR 범위 검사

• atlas-create-access-list - MongoDB Atlas 클러스터의 IP/CIDR 액세스 목록 구성

• atlas-list-db-users - MongoDB Atlas 데이터베이스 사용자 나열

• atlas-create-db-user - MongoDB Atlas 데이터베이스 사용자 생성

• atlas-list-alerts - 프로젝트의 MongoDB Atlas 알림 나열

참고: atlas 도구는 구성 섹션에서 자격 증명을 설정한 경우에만 사용할 수 있습니다.

MongoDB 데이터베이스 도구

• connect - MongoDB 인스턴스에 연결

• find - MongoDB 컬렉션에 대해 find 쿼리 실행

• aggregate - MongoDB 컬렉션에 대해 집계 실행

• count - MongoDB 컬렉션의 문서 수 가져오기

• insert-one - MongoDB 컬렉션에 단일 문서 삽입

• insert-many - MongoDB 컬렉션에 여러 문서 삽입

• create-index - MongoDB 컬렉션의 인덱스 생성

• update-one - MongoDB 컬렉션의 단일 문서 업데이트

• update-many - MongoDB 컬렉션의 여러 문서 업데이트

• rename-collection - MongoDB 컬렉션 이름 변경

• delete-one - MongoDB 컬렉션에서 단일 문서 삭제

• delete-many - MongoDB 컬렉션에서 여러 문서 삭제

• drop-collection - MongoDB 데이터베이스에서 컬렉션 제거

• drop-database - MongoDB 데이터베이스 제거

• list-databases - MongoDB 연결의 모든 데이터베이스 나열

• list-collections - 주어진 데이터베이스의 모든 컬렉션 나열

• collection-indexes - 컬렉션의 인덱스 설명

• collection-schema - 컬렉션의 스키마 설명

• collection-storage-size - 컬렉션의 크기(MB) 가져오기

• db-stats - MongoDB 데이터베이스에 대한 통계 반환

구성

MongoDB MCP Server는 여러 방법으로 구성할 수 있으며, 우선순위는 다음과 같습니다(높은 순에서 낮은 순):

1. 명령줄 인수

2. 환경 변수

구성 옵션

로그 경로

기본 로그 위치는 다음과 같습니다:

• Windows: %LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logs

• macOS/Linux: ~/.mongodb/mongodb-mcp/.app-logs

비활성화된 도구

disabledTools 옵션을 사용하여 특정 도구 또는 도구 범주를 비활성화할 수 있습니다. 이 옵션은 문자열 배열을 허용하며, 각 문자열은 도구 이름, 작업 유형 또는 범주가 될 수 있습니다.

배열을 구성하는 방식은 사용하는 구성 방법의 유형에 따라 다릅니다:

• 환경 변수 구성의 경우 쉼표로 구분된 문자열을 사용합니다: export MDB_MCP_DISABLED_TOOLS="create,update,delete,atlas,collectionSchema".

• 명령줄 인수 구성의 경우 공백으로 구분된 문자열을 사용합니다: --disabledTools create update delete atlas collectionSchema.

도구 범주:

• atlas - 클러스터 목록, 클러스터 생성 등과 같은 MongoDB Atlas 도구.

• mongodb - find, aggregate 등과 같은 MongoDB 데이터베이스 도구.

작업 유형:

• create - 클러스터 생성, 문서 삽입 등과 같은 리소스를 생성하는 도구.

• update - 문서 업데이트, 컬렉션 이름 변경 등과 같은 리소스를 업데이트하는 도구.

• delete - 문서 삭제, 컬렉션 삭제 등과 같은 리소스를 삭제하는 도구.

• read - find, aggregate, 클러스터 목록 등과 같은 리소스를 읽는 도구.

• metadata - 데이터베이스 목록, 컬렉션 목록, 컬렉션 스키마 등과 같은 메타데이터를 읽는 도구.

읽기 전용 모드

readOnly 구성 옵션을 사용하면 MCP 서버가 "read" 및 "metadata" 작업 유형의 도구만 사용하도록 제한할 수 있습니다. 활성화하면 "create", "update" 또는 "delete" 작업 유형을 가진 모든 도구는 서버에 등록되지 않습니다.

이는 데이터나 인프라에 대한 수정을 허용하지 않으면서 분석 목적으로 MongoDB 데이터에 대한 액세스를 제공하려는 시나리오에서 유용합니다.

다음 방법으로 읽기 전용 모드를 활성화할 수 있습니다:

• 환경 변수: export MDB_MCP_READ_ONLY=true

• 명령줄 인수: --readOnly

읽기 전용 모드가 활성화되면 서버 로그에서 이 제한으로 인해 등록이 차단된 도구를 나타내는 메시지를 확인할 수 있습니다.

텔레메트리

telemetry 구성 옵션을 사용하면 텔레메트리 수집을 비활성화할 수 있습니다. 활성화되면 MCP 서버는 사용 데이터를 수집하여 MongoDB로 전송합니다.

다음 방법으로 텔레메트리를 비활성화할 수 있습니다:

• 환경 변수: export MDB_MCP_TELEMETRY=disabled

• 명령줄 인수: --telemetry disabled

• DO_NOT_TRACK 환경 변수: export DO_NOT_TRACK=1

Atlas API 액세스

Atlas API 도구를 사용하려면 MongoDB Atlas에서 서비스 계정을 생성해야 합니다:

ℹ️ 참고: 각 Atlas 작업에 필요한 최소 권한에 대한 자세한 내용은 아래 Atlas API 권한 섹션을 참조하세요.

1. 서비스 계정 생성:

   • cloud.mongodb.com에서 MongoDB Atlas에 로그인합니다.

   • Access Manager > Organization Access로 이동합니다.

   • Add New > Applications > Service Accounts를 클릭합니다.

   • 서비스 계정의 이름, 설명 및 만료 기간을 입력합니다 (예: "MCP, MCP Server Access, 7 days").

   • 사용 사례에 필요한 최소 권한만 할당합니다.

     • 자세한 내용은 Atlas API 권한을 참조하세요.

   • "Create"를 클릭합니다.

서비스 계정에 대한 자세한 내용은 MongoDB Atlas 문서를 확인하세요.

2. 클라이언트 자격 증명 저장:

   • 생성 후 Client ID와 Client Secret이 표시됩니다.

   • 중요: Client Secret은 다시 표시되지 않으므로 즉시 복사하여 저장하세요.

3. 액세스 목록 항목 추가:

   • API 액세스 목록에 IP 주소를 추가합니다.

4. MCP 서버 구성:

   • 아래 구성 방법 중 하나를 사용하여 apiClientId 및 apiClientSecret을 설정합니다.

Atlas API 권한

보안 경고: Organization Owner 역할을 부여하는 것은 거의 필요하지 않으며 보안 위험이 될 수 있습니다. 사용 사례에 필요한 최소 권한만 할당하세요.

빠른 참조: 작업별 필수 역할

• 대부분의 작업에는 프로젝트 수준 역할을 선호하세요. 관리하거나 볼 필요가 있는 특정 프로젝트에만 할당하세요.

• 조직의 모든 프로젝트와 설정에 대한 완전한 관리 제어가 필요하지 않는 한 Organization Owner를 피하세요.

전체 역할 및 권한 목록은 Atlas 사용자 역할 문서를 참조하세요.

구성 방법

환경 변수

접두사 MDB_MCP_ 다음에 옵션 이름을 대문자와 밑줄로 사용하여 환경 변수를 설정합니다:

# Set Atlas API credentials (via Service Accounts)
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

# Set a custom MongoDB connection string
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

export MDB_MCP_LOG_PATH="/path/to/logs"

MCP 구성 파일 예시

환경 변수를 사용한 연결 문자열

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
      }
    }
  }
}

환경 변수를 사용한 Atlas API 자격 증명

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server"],
      "env": {
        "MDB_MCP_API_CLIENT_ID": "your-atlas-service-accounts-client-id",
        "MDB_MCP_API_CLIENT_SECRET": "your-atlas-service-accounts-client-secret"
      }
    }
  }
}

명령줄 인수

서버를 시작할 때 구성 옵션을 명령줄 인수로 전달합니다:

npx -y mongodb-mcp-server --apiClientId="your-atlas-service-accounts-client-id" --apiClientSecret="your-atlas-service-accounts-client-secret" --connectionString="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" --logPath=/path/to/logs

MCP 구성 파일 예시

명령줄 인수를 사용한 연결 문자열

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--connectionString",
        "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
      ]
    }
  }
}

명령줄 인수를 사용한 Atlas API 자격 증명

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--apiClientId",
        "your-atlas-service-accounts-client-id",
        "--apiClientSecret",
        "your-atlas-service-accounts-client-secret"
      ]
    }
  }
}

🤝 기여하기

기여에 관심이 있으신가요? 좋습니다! 코드 기여, 표준, 새 도구 추가 및 문제 해결 지침은 기여 가이드를 확인하세요.