ravenwits/mcp-server-arangodb

ArangoDB를 위한 Model Context Protocol (MCP) 서버

이것은 ArangoDB를 통해 데이터베이스 상호작용 기능을 제공하는 TypeScript 기반 MCP 서버입니다. 핵심 데이터베이스 작업을 구현하며 MCP 도구(tools)를 통해 ArangoDB와 원활한 통합을 지원합니다. Claude 앱 및 Cline과 같이 MCP와 함께 작동하는 VSCode 확장 프로그램에서 사용할 수 있습니다!

arango_query

• AQL 쿼리 실행 - 필수 파라미터로 AQL 쿼리 문자열을 받습니다.

• 매개변수화된 쿼리(parameterized queries)를 위해 선택적으로 바인드 변수(bind variables)를 허용합니다.

• 쿼리 결과를 JSON으로 반환합니다.

arango_insert

• 컬렉션(collections)에 문서(documents) 삽입 - 필수 파라미터로 컬렉션 이름과 문서 객체를 받습니다.

• 제공되지 않은 경우 문서 키(document key)를 자동으로 생성합니다.

• 생성된 문서 메타데이터를 반환합니다.

arango_update

• 기존 문서 업데이트 - 필수 파라미터로 컬렉션 이름, 문서 키, 업데이트 객체를 받습니다.

• 업데이트된 문서 메타데이터를 반환합니다.

arango_remove

• 컬렉션에서 문서 삭제 - 필수 파라미터로 컬렉션 이름과 문서 키를 받습니다.

• 삭제된 문서 메타데이터를 반환합니다.

arango_backup

• 모든 컬렉션을 JSON 파일로 백업 - 필수 파라미터로 출력 디렉토리 경로를 받습니다.

• 현재 데이터를 포함하는 각 컬렉션별 JSON 파일을 생성합니다.

• 데이터 백업 및 마이그레이션(migration) 용도로 유용합니다.

arango_list_collections

• 데이터베이스의 모든 컬렉션 목록 나열 - 이름, ID, 유형을 포함한 컬렉션 정보 배열을 반환합니다.

arango_create_collection

• 데이터베이스에 새 컬렉션 생성 - 필수 파라미터로 컬렉션 이름을 받습니다.
• 선택적으로 컬렉션 유형(document 또는 edge collection)을 지정할 수 있습니다.
• 쓰기 작업에 대한 waitForSync 동작을 구성합니다.
• 이름, 유형, 상태를 포함한 컬렉션 정보를 반환합니다.

arango-server를 NPM을 통해 전역(globally)으로 설치하려면 다음 명령어를 실행하세요:

npm install -g arango-server

설치 없이 arango-server를 직접 실행하려면 다음 명령어를 사용하세요:

npx arango-server

arango-server를 사용하려면

VSCode Copilot 에이전트와 함께 사용하려면, 최소 VSCode 1.99.0 버전이 설치되어 있어야 하며 다음 단계를 따라야 합니다:

MCP 설정 파일 생성 또는 편집:-
워크스페이스 전용 설정 (Workspace-specific configuration): 워크스페이스 내의 .vscode/mcp.json 파일을 생성하거나 편집하세요.
사용자 전용 설정 (User-specific configuration): 선택 사항으로, 모든 워크스페이스에서 MCP 서버를 활성화하려면 VS Code 사용자 설정(mcp)에 서버를 지정하세요.
팁: 설정 파일 구성 방법에 대한 자세한 내용은 VSCode의 MCP 설정 문서를 참조할 수 있습니다.

다음 설정을 추가하세요:
{
"servers": {
"arango-mcp": {
"type": "stdio",
"command": "npx",
"args": ["arango-server"],
"env": {
"ARANGO_URL": "http://localhost:8529",
"ARANGO_DB": "your_database_name",
"ARANGO_USERNAME": "your_username",
"ARANGO_PASSWORD": "your_password"
}
}
}
}

MCP 서버 시작:- VSCode에서 명령 팔레트(Command Palette)를 엽니다 (Ctrl+Shift+P 또는 Mac의 경우 Cmd+Shift+P).

• MCP: Start Server 명령을 실행하고 목록에서 arango-mcp를 선택하세요.

• VSCode에서 명령 팔레트를 엽니다 (

서버 확인:- VSCode에서 채팅 뷰(Chat view)를 열고 에이전트(Agent) 모드로 전환하세요.

• Tools 버튼을 사용하여 arango-server 도구들을 사용할 수 있는지 확인하세요.

다음 경로로 이동하세요: Settings > Developer > Edit Config
또는

• MacOS:
  ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows:
  %APPDATA%/Claude/claude_desktop_config.json

설정을 위해 mcp 문서를 확인해 볼 수도 있습니다.

다음 경로로 이동하세요: Cline Extension > MCP Servers > Edit Configuration
또는

• MacOS:
  ~/Library/Application Support/Code/User/globalStorage/cline.cline/config.json

• Windows:
  %APPDATA%/Code/User/globalStorage/cline.cline/config.json

mcpServers 섹션에 다음 설정을 추가하세요:

{
"mcpServers": {
"arango": {
...

위 설정을 사용하여 이 서버를 WARP에서 작동시킬 수도 있습니다.

서버는 다음 환경 변수(environment variables)가 필요합니다:

ARANGO_URL

• ArangoDB 서버 URL (참고: 8529는 로컬 개발을 위한 ArangoDB 기본 포트입니다)

ARANGO_DB

• 데이터베이스 이름

ARANGO_USERNAME

• 데이터베이스 사용자

ARANGO_PASSWORD

• 데이터베이스 비밀번호

거의 어떤 의미 있는 프롬프트(prompt)를 제공하더라도 Claude는 적절한 함수를 실행하려고 시도할 것입니다.

몇 가지 프롬프트 예시:

• "데이터베이스의 모든 컬렉션(collection) 목록을 나열해줘"
• "모든 사용자를 쿼리(query)해줘"
• "'users' 컬렉션에 이름이 'John Doe'이고 이메일이 'john@example.com'인 새 문서를 삽입해줘"
• "키가 '123456'이거나 이름이 'Jane Doe'인 문서의 나이를 48로 업데이트해줘"
• "'products'라는 이름의 새 컬렉션을 생성해줘"

모든 사용자 쿼리:

{
"query": "FOR user IN users RETURN user"
}

새 문서 삽입:

{
"collection": "users",
"document": {
...

문서 업데이트:

{
"collection": "users",
"key": "123456",
...

문서 삭제:

{
"collection": "users",
"key": "123456"
...

모든 컬렉션 목록 나열:

{
} // 매개변수(parameters)가 필요하지 않음

데이터베이스 컬렉션 백업:

{
"outputDir": "./backup" // 백업 파일에 대한 절대 출력 디렉토리 경로를 지정합니다 (선택 사항)
"collection": "users" // 백업할 컬렉션 이름을 지정합니다 (선택 사항). 컬렉션 이름이 제공되지 않으면 모든 컬렉션이 백업됩니다.
...

새 컬렉션 생성:

{
"name": "products",
"type": "document", // "document" 또는 "edge" (선택 사항, 기본값은 "document")
...

참고: 이 서버는 데이터베이스 구조에 구애받지 않으며, ArangoDB의 문서(document) 및 엣지(edge) 컬렉션 모델을 따르는 한 어떤 컬렉션 이름이나 구조와도 작동할 수 있습니다.

이 도구는 로컬 개발 환경 전용으로 설계되었습니다. 기술적으로는 프로덕션(production) 데이터베이스에 연결할 수 있지만, 이는 심각한 보안 위험을 초래하므로 명시적으로 권장하지 않습니다. 당사는 관심사 분리(separation of concerns)를 유지하고 프로덕션 데이터를 보호하기 위해 개발 데이터베이스에서만 이 도구를 독점적으로 사용합니다.

저장소(repository) 클론

의존성(dependencies) 설치:

npm run build

자동 재빌드(auto-rebuild)를 포함한 개발용:

npm run watch

MCP 서버는 stdio (표준 입출력)를 통해 통신하기 때문에 디버깅(debugging)이 어려울 수 있습니다. 개발 시 권장되는 디버깅 방법은 MCP Inspector를 사용하는 것입니다:

npm run inspector

Inspector는 브라우저에서 디버깅 도구에 접속할 수 있는 URL을 제공합니다.

이 프로젝트는 MIT License 하에 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.