MCP Arangodb Async

一個生產就緒的Model Context Protocol服務器，提供異步優先的Python架構，將高級ArangoDB操作（包括圖數據庫管理、內容轉換、備份恢復和分析功能）暴露給AI助手。

評分 : 2.5分

下載量 : 0

更新時間 : 2026-03-13

什麼是ArangoDB MCP Server?

ArangoDB MCP Server是一個連接AI助手與ArangoDB數據庫的橋樑。它允許您通過自然語言與AI助手（如Claude）對話來執行數據庫操作，包括查詢數據、管理集合、創建圖結構、備份數據等。您不再需要編寫複雜的數據庫查詢語句，只需告訴AI助手您想做什麼。

如何使用ArangoDB MCP Server?

使用ArangoDB MCP Server需要三個步驟：1) 安裝並運行ArangoDB數據庫（推薦使用Docker），2) 安裝MCP服務器軟件，3) 配置您的AI客戶端（如Claude Desktop）連接到該服務器。配置完成後，您就可以在AI助手中直接操作數據庫了。

適用場景

ArangoDB MCP Server特別適合以下場景：需要快速查詢和分析數據庫內容而不想寫代碼；管理複雜的圖數據庫關係；進行代碼庫依賴分析；需要跨多個數據庫操作；希望通過自然語言進行數據備份和恢復。

主要功能

46個MCP工具

提供完整的ArangoDB操作工具集，包括查詢、集合管理、索引操作、圖數據庫管理等46個不同功能。

多租戶支持

支持同時操作多個數據庫，可以在不同環境間切換，執行跨數據庫操作。

MCP設計模式

採用漸進式發現、上下文切換、工具卸載等設計模式，可節省98.7%的令牌使用量。

圖數據庫管理

完整的圖數據庫生命週期管理，包括創建、遍歷、備份和恢復命名圖。

內容格式轉換

支持JSON、Markdown、YAML和表格格式的數據轉換，方便不同場景下的數據展示。

備份與恢復

提供集合和圖級別的備份功能，包含完整性驗證，確保數據安全。

數據分析能力

包含查詢性能分析、執行計劃解釋、圖統計等高級分析功能。

雙傳輸模式

支持stdio（桌面客戶端）和HTTP（Web/容器化）兩種傳輸方式，適應不同部署環境。

優勢

無需編寫代碼即可操作數據庫，通過自然語言與AI助手交互

支持複雜的圖數據庫操作，適合分析代碼依賴、社交網絡等關係數據

多數據庫管理能力，方便在不同環境間切換

完整的備份恢復功能，保障數據安全

生產就緒的架構，包含重試邏輯和優雅降級

侷限性

需要安裝和配置ArangoDB數據庫，有一定技術門檻

依賴AI客戶端（如Claude Desktop）的支持

對於非常複雜的查詢，可能需要多次交互才能達到預期效果

需要Python 3.11+環境，對舊系統支持有限

如何使用

安裝ArangoDB數據庫

使用Docker Compose快速部署ArangoDB數據庫。創建docker-compose.yml和.env文件，然後啟動數據庫服務。

安裝MCP服務器

通過pip安裝mcp-arangodb-async包。確保Python版本為3.11或更高。

創建數據庫和用戶

為MCP服務器創建專用的數據庫和用戶，並設置相應的權限。

配置AI客戶端

在Claude Desktop等AI客戶端的配置文件中添加MCP服務器配置，包括連接信息和環境變量。

重啟並測試

重啟AI客戶端，測試連接是否成功。可以嘗試詢問AI助手關於數據庫的基本信息。

使用案例

代碼庫依賴分析

將代碼庫建模為圖結構，分析模塊和函數之間的依賴關係，發現循環依賴，理解系統架構。

數據備份與恢復

定期備份重要數據集合，或在需要時恢復特定時間點的數據。

跨數據庫數據遷移

在開發、測試和生產環境之間遷移數據，保持數據一致性。

圖數據庫關係查詢

查詢社交網絡中的朋友關係，或產品推薦系統中的關聯規則。

常見問題

為什麼選擇Docker部署ArangoDB？

MCP服務器連接失敗怎麼辦？

支持哪些AI客戶端？

如何管理多個數據庫？

數據安全如何保障？

性能影響大嗎？

🚀 Python版ArangoDB MCP服務器

這是一個生產就緒的模型上下文協議（MCP）服務器，它為Claude Desktop和Augment Code等AI助手提供高級ArangoDB操作。該服務器採用異步優先的Python架構，具備全面的圖管理、靈活的內容轉換（JSON、Markdown、YAML、表格）、備份/恢復功能以及分析能力。

🚀 快速開始

前提條件

安裝 Docker 和 Docker Compose
安裝 Python 3.11+（用於 mcp-arangodb-async）

步驟 1：安裝ArangoDB

創建 docker-compose.yml 文件：

services:
  arangodb:
    image: arangodb:3.11
    environment:
      ARANGO_ROOT_PASSWORD: ${ARANGO_ROOT_PASSWORD:-changeme}
    ports:
      - "8529:8529"
    volumes:
      - arangodb_data:/var/lib/arangodb3
      - arangodb_apps:/var/lib/arangodb3-apps
    healthcheck:
      test: arangosh --server.username root --server.password "$ARANGO_ROOT_PASSWORD" --javascript.execute-string "require('@arangodb').db._version()" > /dev/null 2>&1 || exit 1
      interval: 5s
      timeout: 2s
      retries: 30
    restart: unless-stopped

volumes:
  arangodb_data:
    driver: local
  arangodb_apps:
    driver: local

創建 .env 文件：

# ArangoDB root密碼
ARANGO_ROOT_PASSWORD=changeme

# MCP服務器連接設置
ARANGO_URL=http://localhost:8529
ARANGO_DB=mcp_arangodb_test
ARANGO_USERNAME=mcp_arangodb_user
ARANGO_PASSWORD=mcp_arangodb_password

啟動ArangoDB：

docker compose --env-file .env up -d

步驟 2：安裝 `mcp-arangodb-async`

安裝MCP服務器包：

pip install mcp-arangodb-async

替代方案：使用Conda/Mamba/Micromamba安裝

```bash # 創建環境並安裝 conda create -n mcp-arango python=3.11 conda activate mcp-arango pip install mcp-arangodb-async

或者使用mamba/micromamba：

mamba create -n mcp-arango python=3.11

mamba activate mcp-arango

pip install mcp-arangodb-async

</details>

<details>
<summary><b>替代方案：使用uv安裝</b></summary>
```bash
# 創建環境並安裝
uv venv .venv --python 3.11
uv pip install mcp-arangodb-async

步驟 3：創建數據庫和用戶

為MCP服務器創建數據庫和用戶：

maa db add mcp_arangodb_test \
  --url http://localhost:8529 \
  --with-user mcp_arangodb_user \
  --env-file .env

預期輸出：

The following actions will be performed:
  [ADD] Database 'mcp_arangodb_test'
  [ADD] User 'mcp_arangodb_user' (active: true)
  [GRANT] Permission rw: mcp_arangodb_user → mcp_arangodb_test

Are you sure you want to proceed? [y/N]: y
db add:
[ADDED] Database 'mcp_arangodb_test'
[ADDED] User 'mcp_arangodb_user' (active: true)
[GRANTED] Permission rw: mcp_arangodb_user → mcp_arangodb_test

驗證數據庫連接：

# 設置環境變量
export ARANGO_URL=http://localhost:8529
export ARANGO_DB=mcp_arangodb_test
export ARANGO_USERNAME=mcp_arangodb_user
export ARANGO_PASSWORD=mcp_arangodb_password

# 運行健康檢查
maa health

預期輸出：

{"status": "healthy", "database_connected": true, "database_info": {"version": "3.11.x", "name": "mcp_arangodb_test"}}

步驟 4：配置MCP主機

配置MCP主機以使用該服務器。配置包括數據庫連接的環境變量。配置文件的位置取決於MCP主機。對於Claude Desktop，文件位置如下：

Windows：%APPDATA%\Claude\claude_desktop_config.json
macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

配置內容：

{
  "mcpServers": {
    "arangodb": {
      "command": "python",
      "args": ["-m", "mcp_arangodb_async"],
      "env": {
        "ARANGO_URL": "http://localhost:8529",
        "ARANGO_DB": "mcp_arangodb_test",
        "ARANGO_USERNAME": "mcp_arangodb_user",
        "ARANGO_PASSWORD": "mcp_arangodb_password"
      }
    }
  }
}

替代方案：Conda/Mamba/Micromamba的配置

如果使用conda/mamba/micromamba安裝，請使用 `run` 命令： ```json { "mcpServers": { "arangodb": { "command": "conda", "args": ["run", "-n", "mcp-arango", "maa", "server"], "env": { "ARANGO_URL": "http://localhost:8529", "ARANGO_DB": "mcp_arangodb_test", "ARANGO_USERNAME": "mcp_arangodb_user", "ARANGO_PASSWORD": "mcp_arangodb_password" } } } } ``` 如果使用 `mamba` 或 `micromamba`，請將 `"conda"` 替換為 `"mamba"` 或 `"micromamba"`。

替代方案：uv的配置

如果使用uv安裝，請使用 `uv run`： ```json { "mcpServers": { "arangodb": { "command": "uv", "args": ["run", "--directory", "/path/to/project", "maa", "server"], "env": { "ARANGO_URL": "http://localhost:8529", "ARANGO_DB": "mcp_arangodb_test", "ARANGO_USERNAME": "mcp_arangodb_user", "ARANGO_PASSWORD": "mcp_arangodb_password" } } } } ``` 將 `/path/to/project` 替換為包含 `.venv` 文件夾的目錄。

**更新配置後重啟MCP客戶端**。 **測試連接：** 向MCP客戶端詢問：*"列出ArangoDB數據庫中的所有集合"* 助手應能成功連接並列出集合。

✨ 主要特性

✅ 46個MCP工具 - 完成ArangoDB操作（查詢、集合、索引、圖）
✅ 多租戶支持 - 處理多個數據庫，支持環境切換和跨數據庫操作
✅ MCP設計模式 - 漸進式發現、上下文切換、工具卸載（節省98.7%的令牌）
✅ 圖管理 - 創建、遍歷、備份/恢復命名圖
✅ 內容轉換 - 支持JSON、Markdown、YAML和表格格式
✅ 備份/恢復 - 支持集合和圖級別的備份並進行驗證
✅ 分析功能 - 查詢分析、執行計劃解釋、圖統計
✅ 雙傳輸方式 - stdio（桌面客戶端）和HTTP（Web/容器化）
✅ Docker支持 - 可在Docker中運行以實現隔離和可重複性
✅ 生產就緒 - 具備重試邏輯、優雅降級和全面的錯誤處理
✅ 類型安全 - 所有工具參數均使用Pydantic進行驗證

🏗️ 架構

┌────────────────────┐      ┌─────────────────────┐       ┌──────────────────┐
│   MCP Client       │      │  ArangoDB MCP       │       │   ArangoDB       │
│ (Claude, Augment)  │─────▶│  Server (Python)    │─────▶│  (Docker)        │
│                    │      │  • 46 Tools         │       │  • Multi-Model   │
│                    │      │  • Multi-Tenancy    │       │  • Graph Engine  │
│                    │      │  • Graph Mgmt       │       │  • AQL Engine    │
│                    │      │  • MCP Patterns     │       │                  │
└────────────────────┘      └─────────────────────┘       └──────────────────┘

💻 使用示例

代碼庫圖分析用例

將代碼庫建模為圖，以分析依賴關係、查找循環引用並理解架構。以下是較長的代碼庫分析示例的節選：

# 1. 創建圖結構
向Claude詢問: "創建一個名為 'codebase' 的圖，包含頂點集合 'modules' 和 'functions'，以及連接函數的邊集合 'calls'"

# 2. 導入代碼庫數據
向Claude詢問: "將這些模塊插入 'modules' 集合: [...]"

# 3. 分析依賴關係
向Claude詢問: "使用圖遍歷查找所有依賴 'auth' 模塊的函數"

# 4. 檢測循環依賴
向Claude詢問: "檢查代碼庫圖中是否存在循環依賴"

# 5. 生成架構圖
向Claude詢問: "將代碼庫圖結構導出為Markdown以進行可視化"

📖 更多示例

📚 詳細文檔

入門指南

配置

用戶指南

開發者指南

示例

代碼庫依賴分析

📖 完整文檔：https://github.com/PCfVW/mcp-arango-async/tree/master/docs

🔧 技術細節

可用工具

服務器提供 46個MCP工具，分為11個類別：

多租戶工具（4個）

arango_set_focused_database - 設置會話的聚焦數據庫
arango_get_focused_database - 獲取當前聚焦的數據庫
arango_list_available_databases - 列出所有配置的數據庫
arango_get_database_resolution - 顯示數據庫解析算法

核心數據操作（7個）

arango_query - 執行AQL查詢
arango_list_collections - 列出所有集合
arango_insert - 插入文檔
arango_update - 更新文檔
arango_remove - 刪除文檔
arango_create_collection - 創建集合
arango_backup - 備份集合

索引管理（3個）

arango_list_indexes - 列出索引
arango_create_index - 創建索引
arango_delete_index - 刪除索引

查詢分析（3個）

arango_explain_query - 解釋查詢執行計劃
arango_query_builder - 構建AQL查詢
arango_query_profile - 分析查詢性能

數據驗證（4個）

arango_validate_references - 驗證文檔引用
arango_insert_with_validation - 帶驗證的插入操作
arango_create_schema - 創建JSON模式
arango_validate_document - 根據模式驗證文檔

批量操作（2個）

arango_bulk_insert - 批量插入文檔
arango_bulk_update - 批量更新文檔

圖管理（7個）

arango_create_graph - 創建命名圖
arango_list_graphs - 列出所有圖
arango_add_vertex_collection - 添加頂點集合
arango_add_edge_definition - 添加邊定義
arango_add_vertex - 添加頂點
arango_add_edge - 添加邊
arango_graph_traversal - 遍歷圖

圖遍歷（2個）

arango_traverse - 圖遍歷
arango_shortest_path - 查找最短路徑

圖備份/恢復（5個）

arango_backup_graph - 備份單個圖
arango_restore_graph - 恢復單個圖
arango_backup_named_graphs - 備份所有命名圖
arango_validate_graph_integrity - 驗證圖的完整性
arango_graph_statistics - 圖統計

健康與狀態（1個）

arango_database_status - 獲取所有數據庫的綜合狀態

工具別名（2個）

arango_graph_traversal - arango_traverse 的別名
arango_add_vertex - arango_insert 的別名

MCP設計模式工具（8個）

arango_search_tools - 按關鍵字搜索工具
arango_list_tools_by_category - 按類別列出工具
arango_switch_workflow - 切換工作流上下文
arango_get_active_workflow - 獲取活動工作流
arango_list_workflows - 列出所有工作流
arango_advance_workflow_stage - 推進工作流階段
arango_get_tool_usage_stats - 獲取工具使用統計信息
arango_unload_tools - 卸載特定工具

📖 完整工具參考：https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/tools-reference.md 📖 MCP設計模式指南：https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/mcp-design-patterns.md

🛠️ 故障排除

常見問題

數據庫連接失敗：

# 檢查ArangoDB是否正在運行
docker ps | grep arangodb

# 測試連接
curl http://localhost:8529/_api/version

# 檢查憑證
maa health

Claude Desktop中服務器無法啟動：

# 驗證Python安裝
python --version  # 必須是3.11+

# 直接測試模塊
maa health

# 檢查Claude Desktop日誌
# Windows: %APPDATA%\Claude\logs\
# macOS: ~/Library/Logs/Claude/

工具執行錯誤：

驗證ArangoDB是否健康：docker compose ps
檢查環境變量是否設置正確
查看服務器日誌以獲取詳細錯誤信息

📖 完整故障排除指南

🐳 為什麼使用Docker部署ArangoDB？

✅ 穩定性 - 隔離環境，無主機衝突
✅ 零安裝 - 使用 docker compose 啟動/停止
✅ 可重複性 - 所有環境使用相同鏡像
✅ 健康檢查 - 內置就緒驗證
✅ 快速重置 - 輕鬆重新創建乾淨實例
✅ 可移植性 - 在Windows/macOS/Linux上保持一致