mcp-arangodb-async

适用于 Python 的 ArangoDB MCP 服务

一个可用于生产环境的模型上下文协议（MCP）服务，可向 Claude Desktop 和 Augment Code 等 AI 助手提供高级 ArangoDB 操作。具备异步优先的 Python 架构、全面的图管理功能、灵活的内容转换（JSON、Markdown、YAML、表格）、备份/恢复功能以及分析能力。

快速链接

📚 文档： https://github.com/PCfVW/mcp-arango-async/tree/master/docs

🚀 快速入门： https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/quickstart.md

🔧 ArangoDB 设置： https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/install-arangodb.md

🗄️ 多租户指南： https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/multi-tenancy-guide.md

⚙️ CLI 参考： https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/cli-reference.md

📖 工具参考： 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

📝 变更日志： https://github.com/PCfVW/mcp-arango-async/blob/master/docs/developer-guide/changelog.md

🐛 问题： https://github.com/PCfVW/mcp-arango-async/issues

功能

• ✅ 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     │       │                  │
└────────────────────┘      └─────────────────────┘       └──────────────────┘

开始使用 ArangoDB

前置条件

• 已安装 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 password
ARANGO_ROOT_PASSWORD=changeme

# MCP Server connection settings
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

# Create environment and install
conda create -n mcp-arango python=3.11
conda activate mcp-arango
pip install mcp-arangodb-async

# Or with mamba/micromamba:
# mamba create -n mcp-arango python=3.11
# mamba activate mcp-arango
# pip install mcp-arangodb-async

# Create environment and install
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

验证数据库连接：

# Set environment variables
export ARANGO_URL=http://localhost:8529
export ARANGO_DB=mcp_arangodb_test
export ARANGO_USERNAME=mcp_arangodb_user
export ARANGO_PASSWORD=mcp_arangodb_password

# Run health check
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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

更新配置后，重启 MCP 客户端。

测试连接：

向 MCP 客户端提问："列出 ArangoDB 数据库中的所有集合"

助手应能成功连接并列出你的集合。

可用工具

该服务提供 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

使用案例：代码库图分析

将代码库建模为图，以分析依赖关系、查找循环引用并了解架构。以下是较长的代码库分析示例中的摘录：

# 1. Create graph structure
Ask Claude: "Create a graph called 'codebase' with vertex collections 'modules' and 'functions', and edge collection 'calls' connecting functions"

# 2. Import codebase data
Ask Claude: "Insert these modules into the 'modules' collection: [...]"

# 3. Analyze dependencies
Ask Claude: "Find all functions that depend on the 'auth' module using graph traversal"

# 4. Detect circular dependencies
Ask Claude: "Check for circular dependencies in the codebase graph"

# 5. Generate architecture diagram
Ask Claude: "Export the codebase graph structure as Markdown for visualization"

📖 更多示例

文档

入门

• ArangoDB 安装
• 快速入门指南
• 从源代码安装
• 首次交互

配置

• 传输配置
• 环境变量

用户指南

• 工具参考
• 故障排除

开发者指南

• 架构概览
• 低级 MCP 的设计依据
• HTTP 传输
• 变更日志

示例

• 代码库依赖分析

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

故障排除

常见问题

数据库连接失败：

# Check ArangoDB is running
docker ps | grep arangodb

# Test connection
curl http://localhost:8529/_api/version

# Check credentials
maa health

Claude Desktop 中的服务无法启动：

# Verify Python installation
python --version  # Must be 3.11+

# Test module directly
maa health

# Check Claude Desktop logs
# Windows: %APPDATA%\Claude\logs\
# macOS: ~/Library/Logs/Claude/

工具执行错误：

• 确认 ArangoDB 运行正常：docker compose ps
• 检查环境变量是否设置正确
• 查看服务日志以获取详细错误信息

📖 完整故障排除指南

为什么为 ArangoDB 使用 Docker？

✅ 稳定性 - 隔离环境，不会与主机产生冲突
✅ 零安装 - 使用 docker compose 启动／停止
✅ 可复现性 - 所有环境使用相同的镜像
✅ 健康检查 - 内置就绪状态验证
✅ 快速重置 - 轻松重新创建干净的实例
✅ 可移植性 - 在 Windows/macOS/Linux 上保持一致

许可证

• 本项目： Apache License 2.0
• ArangoDB 3.11： Apache License 2.0
• ArangoDB 3.12+： Business Source License 1.1 (BUSL-1.1)

⚠️ 重要提示： 本仓库不授予使用 ArangoDB 二进制文件的权利。你必须遵守适用于所部署版本的 ArangoDB 许可证。

📖 许可证详情

贡献

欢迎贡献！请参阅我们的文档，了解相关指南。

📖 架构决策

支持

• 问题
• 讨论
• 文档

致谢

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

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