article

README

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

📄 许可证

本项目：采用Apache License 2.0
ArangoDB 3.11：采用Apache License 2.0
ArangoDB 3.12+：采用商业源许可证1.1（BUSL - 1.1）

⚠️ 重要提示：本仓库不授予ArangoDB二进制文件的使用权限。您必须遵守ArangoDB部署版本的许可证规定。 📖 许可证详情

🤝 贡献

欢迎贡献代码！请参阅我们的文档以获取指南。 📖 架构决策

📞 支持

🙏 致谢

本项目基于以下工具构建：

Model Context Protocol 由Anthropic提供
python - arango - 官方ArangoDB Python驱动
Pydantic - 数据验证
Starlette - HTTP传输
ArangoDB - 多模型数据库