ArangoDB를 위한 Model Context Protocol (MCP) 서버
이것은 ArangoDB를 통해 데이터베이스 상호작용 기능을 제공하는 TypeScript 기반 MCP 서버입니다. 핵심 데이터베이스 작업을 구현하며 MCP 도구(tools)를 통해 ArangoDB와 원활한 통합을 지원합니다. Claude 앱 및 Cline과 같이 MCP와 함께 작동하는 VSCode 확장 프로그램에서 사용할 수 있습니다!
arango_query
arango_insert
arango_update
arango_remove
arango_backup
-
모든 컬렉션을 JSON 파일로 백업 - 필수 파라미터로 출력 디렉토리 경로를 받습니다.
-
현재 데이터를 포함하는 각 컬렉션별 JSON 파일을 생성합니다.
-
데이터 백업 및 마이그레이션(migration) 용도로 유용합니다.
arango_list_collections
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).
서버 확인:- VSCode에서 채팅 뷰(Chat view)를 열고 에이전트(Agent) 모드로 전환하세요.
Tools 버튼을 사용하여 arango-server 도구들을 사용할 수 있는지 확인하세요.
다음 경로로 이동하세요: Settings > Developer > Edit Config
또는
설정을 위해 mcp 문서를 확인해 볼 수도 있습니다.
다음 경로로 이동하세요: Cline Extension > MCP Servers > Edit Configuration
또는
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'이고 이메일이 '[email protected]'인 새 문서를 삽입해줘"
- "키가 '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 파일을 참조하세요.