Docs Menu
Docs Home
/ /
구성
Docs Home
/
도구
/
MongoDB MCP 서버
/
구성
Docs Home
/
도구
/
MongoDB MCP 서버
/
구성

MongoDB MCP 서버 문제 해결

이 페이지의 정보를 사용하여 MongoDB MCP 서버 관련 문제를 해결하세요.

로그 파일

MCP 서버에 문제가 있는 경우 MCP 서버 로그에서 문제 해결에 도움이 되는 정보를 확인합니다.

기본값 으로 MCP 서버는 디스크에 로그를 기록하고 MCP 클라이언트 에도 로그를 보냅니다. loggers 옵션을 변경하여 로그가 전송되는 위치를 지정할 수 있습니다. MCP 서버 옵션에 대한 자세한 내용은 MongoDB MCP 서버 구성 옵션을 참조하세요.

다음 표는 MCP 서버가 로그 파일을 저장하는 기본값 디렉토리를 보여줍니다.

운영 체제
기본 로그 디렉토리

Windows

%LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logs

macOS 및 Linux

~/.mongodb/mongodb-mcp/.app-logs

로그 경로를 변경하려면 다음 중 하나를 설정하다 .

  • logPath 옵션을 JSON 구성 파일 또는 MCP 서버를 시작할 때 명령줄 에 추가합니다.

  • MDB_MCP_LOG_PATH 환경 변수

연결 문자열 문제

구성 파일 올바르고 MongoDB deployment 에 유효한 연결 문자열 사용하고 있는지 확인합니다.

연결 문자열 형식 지정 및 예시는 연결 문자열.를 참조하세요.

HTTP 전송 문제

HTTP 전송을 사용 중이고 연결 문제가 발생하는 경우:

  • 클라이언트 연결 URL /mcp 엔드포인트 경로가 포함되어 있는지 확인합니다.

    http://<server-address>:3000/mcp

  • 원격 서버 (다른 컴퓨터, 컨테이너 또는 cloud 인스턴스)에 연결하는 경우, 원격 연결을 허용하려면 서버 --httpHost=0.0.0.0 (으)로 시작되었는지 확인하세요.

    npx -y mongodb-mcp-server@latest --transport http --httpHost=0.0.0.0 --readOnly

  • 지정된 포트가 열려 있고 클라이언트 컴퓨터에서 액세스할 수 있는지 확인합니다.

Atlas 도구 및 데이터베이스 도구 구성 가이드

개요

MongoDB MCP 서버는 Atlas 인프라를 관리하기 위한 Atlas 도구, Atlas CLI 제공하는 것과 유사한 로컬 배포를 관리하기 위한Local Atlas 도구, 데이터 작업을 위한 데이터베이스 도구라는 세 가지 주요 도구 범주를 제공합니다. 다음 표에서는 각 도구의 구성을 비교합니다.

구성 비교 표

구성 측면
Atlas 도구
로컬 Atlas 도구
Database Tools

인증 요구 사항

Required: Atlas API credentials
• apiClientId (Service Account ID)
• apiClientSecret (Service Account Secret)
Required: Docker runtime
• No additional credentials needed
• Automatically manages local deployments
Optional: Multiple connection methods
• Pre-configured connection string
• Atlas credentials for atlas-connect-cluster
• Runtime connection via connect tool
• Local deployment via atlas-local-connect-deployment

연결 메서드

API-based connection to Atlas Management API
• No direct database connection needed
• Uses Atlas REST API endpoints
Local deployment management
• Uses Docker containers
• No external network access required
Direct connection to MongoDB database. Multiple options available:
• Configured connection string
• Runtime connection prompt
• Atlas cluster discovery
• Local deployment connection

권한 요구 사항

Service Account Roles (Atlas project-level):
• Project Read Only (minimum for read operations)
• Project Owner (for cluster creation/management)
• Organization Owner (for project creation)
System Requirements:
• Docker runtime permissions
• Local file system access
• Container management capabilities
Database User Roles (when applicable):
• readAnyDatabase (read-only mode)
• readWriteAnyDatabase (full operations)
• Custom roles for specific databases/collections

구성 옵션

Environment Variables:
MDB_MCP_API_CLIENT_ID or
MDB_MCP_API_CLIENT_SECRET

Command Line:
• --apiClientId
• --apiClientSecret
Environment Variables:
• DOCKER_HOST (optional)

Command Line:
• No specific MCP configuration required
• Automatically detects Docker runtime
Environment Variables (optional):
MDB_MCP_CONNECTION_STRING

Command Line (optional):
• Connection string as positional argument:
--connectionString

Runtime Methods:
• Interactive connection via LLM prompts
• Atlas credential-based discovery

읽기 전용 모드 영향

• Read operations: ✅ Available
• Cluster inspection: ✅ Available
• Cluster creation: ❌ Disabled
• User management: ❌ Disabled
• Local deployment creation: ✅ Available
• Deployment inspection: ✅ Available
• Container management: ✅ Available
• No read-only restrictions
• Read operations: ✅ Available
• Query operations: ✅ Available
• Aggregations: ✅ Available as long as they don't have a $out or $merge stage.
• Insert/Update/Delete: ❌ Disabled
• Index creation: ❌ Disabled

도구 카테고리

Can be disabled with:
--disabledTools atlas or
MDB_MCP_DISABLED_TOOLS="atlas"
Can be disabled with:
--disabledTools atlas or
MDB_MCP_DISABLED_TOOLS="atlas"
Can be disabled with:
--disabledTools mongodb or
MDB_MCP_DISABLED_TOOLS="mongodb"

네트워크 요구 사항

Outbound HTTPS to Atlas API:
• Standard internet connection
Local Docker Network:
• Docker daemon access
• Local port availability
• No external network requirements
Connection to MongoDB cluster (when applicable):
• Atlas: mongodb+srv:// (port 27017)
• Sharded clusters (port 27016)
• Self-managed: Custom host/port
• Local deployments: Docker network
• VPC/network access as required

사용 가능한 작업

• Organization management
• Project management
• Cluster lifecycle (create, inspect, delete)
• Database user management
• Access list configuration
• Performance Advisor recommendations
• Alert management
• Local deployment creation and management
• Container lifecycle operations
• Local cluster configuration
• Development environment setup
• Testing deployment management
• CRUD operations (find, insert, update, delete)
• Aggregation pipelines
• Index management
• Collection and database administration
• Schema inspection
• Vector search operations
• Data export

오류 시나리오

Missing API Credentials:
Atlas tools return: "Atlas API credentials not configured"

Insufficient Permissions:
HTTP 403 errors from Atlas API
Docker Unavailable:
"Docker daemon not running" or "Docker not installed"

Container Issues:
Port conflicts, resource constraints
Connection Failures (when configured):
Network timeouts, authentication failures

Missing Database Permissions:
MongoDB authorization errors

임시 자격 증명

Not applicable:
Uses persistent service account credentials
Not applicable:
Local deployments use container-managed authentication
Auto-generated database users (when applicable):
When using Atlas API credentials without connection string:
• Random username/password
• 4-hour expiration by default
• Automatic role assignment

데이터베이스 연결 방법

데이터베이스 도구는 다양한 사용 사례와 보안 요구 사항을 수용할 수 있도록 여러 연결 방법을 지원 .

  • 사전구성된 연결 문자열: connectionString 영구 데이터베이스 액세스 위한 CLI, 환경 변수 또는 구성 파일 통해 를 구성합니다.

  • Atlas Cluster Connect: atlas-connect-cluster Atlas API 자격 증명 과 함께 도구를 사용하여 Atlas cluster를 자동으로 검색하고 연결할 수 있습니다.

  • 런타임 연결:connect 도구를 사용하여 LLM 대화 중에 대화형으로 연결 문자열을 제공할 수 있으며, 사전 구성이 필요하지 않습니다.

  • 로컬 배포연결: Docker 와 함께 를 사용하여 로컬 Atlas 배포를 만들고 연결합니다 - Docker 필요하지만 구성은 필요하지 않습니다.atlas-local-connect-deployment

보안 권장 사항:

  • 프로덕션 데이터베이스: 환경 변수 또는 Atlas API 자격 증명 통해 사전 구성된 연결 문자열을 사용하여 안전하고 자동화된 연결을 사용할 수 있습니다.

  • 개발/테스트: 런타임 연결 또는 로컬 배포는 지속적인 구성 없이 유연성을 제공합니다.

  • 채팅 보안: 채팅 기록이 저장되거나 제3자와 공유되지 않는다고 확신하는 경우가 아니라면 런타임 연결 방법을 피하세요.

자세히 알아보기

돌아가기

메모리 오버플로

다음

도구

이 페이지의 내용