MCP MongoDB 서버

NPM 버전 NPM 다운로드 NPM 라이센스 대장간 배지

LLM이 MongoDB 데이터베이스와 상호 작용할 수 있도록 하는 모델 컨텍스트 프로토콜 서버입니다. 이 서버는 표준화된 인터페이스를 통해 컬렉션 스키마를 검사하고 MongoDB 작업을 실행하는 기능을 제공합니다.

데모

MCP MongoDB 서버 데모 | Claude Desktop

Related MCP server: MongoDB MCP Server for LLMs

주요 특징

스마트 ObjectId 처리

문자열 ID와 MongoDB ObjectId 간의 지능형 변환
objectIdMode 매개변수로 구성 가능:
- "auto" : 필드 이름을 기준으로 변환(기본값)
- "none" : 변환 없음
- "force" : 모든 문자열 ID 필드를 ObjectId로 강제 적용합니다.

유연한 구성

환경 변수 :
- MCP_MONGODB_URI : MongoDB 연결 URI
- MCP_MONGODB_READONLY : "true"로 설정하면 읽기 전용 모드를 활성화합니다.
명령줄 옵션 :
- --read-only 또는 -r : 읽기 전용 모드로 연결

읽기 전용 모드

쓰기 작업(update, insert, createIndex)에 대한 보호
최적의 성능을 위해 MongoDB의 보조 읽기 기본 설정을 사용합니다.
프로덕션 데이터베이스에 안전하게 연결하는 데 이상적입니다.

MongoDB 운영

읽기 작업 :
- 선택적 실행 계획 분석을 통한 문서 쿼리
- 집계 파이프라인 실행
- 기준과 일치하는 문서 계산
- 컬렉션 스키마 정보 가져오기
쓰기 작업 (읽기 전용 모드가 아닌 경우):
- 문서 업데이트
- 새 문서 삽입
- 인덱스 생성

LLM 통합

향상된 LLM 상호 작용을 위한 컬렉션 완료
향상된 컨텍스트 이해를 위한 스키마 추론
데이터 통찰력을 위한 수집 분석

설치

글로벌 설치

지엑스피1

개발을 위해

# Clone repository
git clone https://github.com/kiliczsh/mcp-mongo-server.git
cd mcp-mongo-server

# Install dependencies
npm install

# Build
npm run build

# Development with auto-rebuild
npm run watch

용법

기본 사용법

# Start server with MongoDB URI
npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database

# Connect in read-only mode
npx -y mcp-mongo-server mongodb://muhammed:kilic@localhost:27017/database --read-only

환경 변수

환경 변수를 사용하여 서버를 구성할 수 있는데, 이는 CI/CD 파이프라인, Docker 컨테이너에 특히 유용하며, 명령 인수에서 연결 세부 정보를 노출하고 싶지 않을 때도 유용합니다.

# Set MongoDB connection URI
export MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database"

# Enable read-only mode
export MCP_MONGODB_READONLY="true"

# Run server (will use environment variables if no URI is provided)
npx -y mcp-mongo-server

Claude Desktop 구성에서 환경 변수 사용:

{
  "mcpServers": {
    "mongodb-env": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database",
        "MCP_MONGODB_READONLY": "true"
      }
    }
  }
}

Docker에서 환경 변수 사용하기:

# Build
docker build -t mcp-mongo-server .

# Run
docker run -it -d -e MCP_MONGODB_URI="mongodb://muhammed:kilic@localhost:27017/database" -e MCP_MONGODB_READONLY="true" mcp-mongo-server

# or edit docker-compose.yml and run
docker-compose up -d

Claude Desktop과 통합

수동 구성

Claude Desktop의 구성 파일에 서버 구성을 추가합니다.

MacOS : ~/Library/Application Support/Claude/claude_desktop_config.json Windows : %APPDATA%/Claude/claude_desktop_config.json

명령줄 인수 접근 방식:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    },
    "mongodb-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database",
        "--read-only"
      ]
    }
  }
}

환경 변수 접근 방식:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database"
      }
    },
    "mongodb-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server"
      ],
      "env": {
        "MCP_MONGODB_URI": "mongodb://muhammed:kilic@localhost:27017/database",
        "MCP_MONGODB_READONLY": "true"
      }
    }
  }
}

GitHub 패키지 사용법:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "github:kiliczsh/mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    },
    "mongodb-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "github:kiliczsh/mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database",
        "--read-only"
      ]
    }
  }
}

Windsurf 및 Cursor와의 통합

MCP MongoDB 서버는 Claude Desktop과 비슷한 방식으로 Windsurf 및 Cursor와 함께 사용할 수 있습니다.

윈드서핑 구성

Windsurf 구성에 서버를 추가합니다.

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    }
  }
}

커서 구성

커서의 경우 설정에 서버 구성을 추가합니다.

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mongo-server",
        "mongodb://muhammed:kilic@localhost:27017/database"
      ]
    }
  }
}

Claude Desktop 구성에 표시된 것과 동일한 패턴을 따라 Windsurf와 Cursor 모두에서 환경 변수 접근 방식을 사용할 수도 있습니다.

자동 설치

대장간 사용하기 :

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

mcp-get 사용하기 :

npx @michaellatman/mcp-get@latest install mcp-mongo-server

사용 가능한 도구

쿼리 작업

쿼리 : MongoDB 쿼리 실행

{
  collection: "users",
  filter: { age: { $gt: 30 } },
  projection: { name: 1, email: 1 },
  limit: 20,
  explain: "executionStats"  // Optional
}

aggregate : 집계 파이프라인 실행

{
  collection: "orders",
  pipeline: [
    { $match: { status: "completed" } },
    { $group: { _id: "$customerId", total: { $sum: "$amount" } } }
  ],
  explain: "queryPlanner"  // Optional
}

count : 일치하는 문서 수 계산

{
  collection: "products",
  query: { category: "electronics" }
}

쓰기 작업

업데이트 : 문서 수정

{
  collection: "posts",
  filter: { _id: "60d21b4667d0d8992e610c85" },
  update: { $set: { title: "Updated Title" } },
  upsert: false,
  multi: false
}

삽입 : 새 문서 추가

{
  collection: "comments",
  documents: [
    { author: "user123", text: "Great post!" },
    { author: "user456", text: "Thanks for sharing" }
  ]
}

createIndex : 컬렉션 인덱스 생성

{
  collection: "users",
  indexes: [
    {
      key: { email: 1 },
      unique: true,
      name: "email_unique_idx"
    }
  ]
}

시스템 운영

serverInfo : MongoDB 서버 세부 정보 가져오기
```
{
  includeDebugInfo: true  // Optional
}
```

디버깅

MCP 서버는 stdio를 통해 통신하므로 디버깅이 어려울 수 있습니다. MCP Inspector를 사용하면 더 나은 가시성을 확보할 수 있습니다.

npm run inspector

이렇게 하면 브라우저에서 디버깅 도구에 액세스할 수 있는 URL이 제공됩니다.

특허

이 MCP 서버는 MIT 라이선스에 따라 라이선스가 부여됩니다. 즉, MIT 라이선스의 조건에 따라 소프트웨어를 자유롭게 사용, 수정 및 배포할 수 있습니다. 자세한 내용은 프로젝트 저장소의 LICENSE 파일을 참조하세요.

MongoDB