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上保持一致