MCP Server for ArangoDB

ArangoDB 的 MCP 服务

适用于 ArangoDB 的模型上下文协议服务

这是一个基于 TypeScript 的 MCP 服务，可通过 ArangoDB 提供数据库交互能力。它实现了核心数据库操作，并支持通过 MCP 工具与 ArangoDB 无缝集成。你可以将它与 Claude 应用以及支持 MCP 的 VSCode 扩展（例如 Cline）搭配使用！

功能

工具

工具	类别	只读	修改数据／架构	用途
arango_query	查询	否	可能	执行通用 AQL，支持绑定变量、结果数量上限和查询保护措施。
arango_read_query	查询	是	否	执行只读 AQL，并拒绝写入／DDL 关键字。
arango_validate_query	查询	是	否	解析并验证 AQL，但不执行。
arango_explain_query	查询	是	否	检查 AQL 执行计划、索引使用情况和优化器输出。
arango_describe_database	发现	是	否	概述集合、计数、索引和样本字段。
arango_list_collections	发现	是	否	列出已配置数据库中的集合。
arango_get_collection	发现	是	否	返回集合属性、计数和索引。
arango_create_collection	集合	否	是	创建文档集合或边集合。
arango_drop_collection	集合	否	是	删除集合，需提供 confirm: true。
arango_get_document	文档	是	否	根据集合和 _key 获取一份文档。
arango_list_documents	文档	是	否	使用 limit 和 offset 分页列出文档。
arango_count_documents	文档	是	否	统计集合中的文档数量。
arango_sample_documents	文档	是	否	返回少量随机样本，用于发现架构。
arango_insert	文档	否	是	向集合中插入一份文档。
arango_bulk_insert	文档	否	是	在一个请求中最多插入 1000 份文档。
arango_update	文档	否	是	根据 _key 对一份文档进行部分更新。
arango_bulk_update	文档	否	是	根据 _key 或 _id 更新最多 1000 份文档。
arango_remove	文档	否	是	根据 _key 删除一份文档。
arango_list_indexes	索引	是	否	列出集合的索引。
arango_create_index	索引	否	是	创建持久索引、地理索引、TTL 索引或倒排索引。
arango_list_views	ArangoSearch	是	否	列出 ArangoSearch 和搜索别名视图。
arango_create_search_view	ArangoSearch	否	是	创建与集合关联的 ArangoSearch 视图。
arango_search	ArangoSearch	是	否	使用支持分析器的 BM25 排序搜索 ArangoSearch 视图。
arango_list_analyzers	分析器	是	否	列出 ArangoSearch 分析器。
arango_create_analyzer	分析器	否	是	创建 ArangoSearch 分析器。
arango_list_graphs	图	是	否	列出命名图。
arango_create_graph	图	否	是	创建包含一个边定义的命名图。
arango_insert_edge	图	否	是	插入包含 _from 和 _to 的边文档。
arango_traverse	图	是	否	使用边集合或命名图，从起始顶点遍历边。
arango_shortest_path	图	是	否	使用边集合或命名图，查找两个顶点之间的最短路径。
arango_backup	备份	否	文件系统	将集合备份为 ARANGO_BACKUP_ROOT 下的 JSON 文件。

所有工具成功时都会返回 JSON 文本和 structuredContent。读取密集型工具提供有上限的 limit 参数，使响应更适合 Agent 使用。查询工具还支持适用情况下的保护措施，例如 memoryLimit、maxRuntime 和 failOnWarning。

安装

通过 NPM 安装

要通过 NPM 全局安装 arango-server，请运行以下命令：

npm install -g arango-server

通过 NPX 运行

若要直接运行 arango-server 而无需安装，请使用以下命令：

npx -y arango-server

配置 VSCode Agent

要将 arango-server 与 VSCode Copilot Agent 搭配使用，必须至少安装 VSCode 1.99.0，并按以下步骤操作：

1. 创建或编辑 MCP 配置文件：

   • 工作区专属配置：在工作区中创建或编辑 .vscode/mcp.json 文件。

   • 用户专属配置：也可以在 setting(mcp) VS Code 用户设置中指定该服务，以便在所有工作区中启用 MCP 服务。

     提示：有关如何设置配置文件的详细信息，请参阅 VSCode 的 MCP 配置文档。

2. 添加以下配置：

   {
     "servers": {
       "arango-mcp": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "arango-server"],
         "env": {
           "ARANGO_URL": "http://localhost:8529",
           "ARANGO_DB": "your_database_name",
           "ARANGO_USERNAME": "your_username",
           "ARANGO_PASSWORD": "your_password"
         }
       }
     }
   }
   

3. 启动 MCP 服务：

   • 在 VSCode 中打开命令面板（Mac 上按 Ctrl+Shift+P 或 Cmd+Shift+P）。
   • 运行命令 MCP: Start Server，然后从列表中选择 arango-mcp。

4. 验证服务：

   • 在 VSCode 中打开聊天视图并切换到 Agent 模式。
   • 使用 Tools 按钮，确认可以使用 arango-server 工具。

与 Claude Desktop 搭配使用

前往：Settings > Developer > Edit Config，或

• MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

也可以查看 MCP 文档进行设置。

与 OpenCode 搭配使用

在 OpenCode 配置文件中添加以下配置，例如 opencode.json 或 opencode.jsonc：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "arango": {
      "type": "local",
      "command": ["npx", "-y", "arango-server"],
      "enabled": true,
      "environment": {
        "ARANGO_URL": "your_database_url",
        "ARANGO_DB": "your_database_name",
        "ARANGO_USERNAME": "your_username",
        "ARANGO_PASSWORD": "your_password"
      }
    }
  }
}

重启 OpenCode 后，请让它在处理 ArangoDB 任务时使用 arango MCP 工具。

与 Cline VSCode 扩展搭配使用

前往：Cline Extension > MCP Servers > Edit Configuration，或

• MacOS：~/Library/Application Support/Code/User/globalStorage/cline.cline/config.json
• Windows：%APPDATA%/Code/User/globalStorage/cline.cline/config.json

在 mcpServers 部分添加以下配置：

{
  "mcpServers": {
    "arango": {
      "command": "npx",
      "args": ["-y", "arango-server"],
      "env": {
        "ARANGO_URL": "your_database_url",
        "ARANGO_DB": "your_database_name",
        "ARANGO_USERNAME": "your_username",
        "ARANGO_PASSWORD": "your_password"
      }
    }
  }
}

也可以使用上述配置，在 WARP 中启用此服务。

环境变量

此服务需要以下环境变量：

• ARANGO_URL - ArangoDB 服务 URL（注意：本地开发时 ArangoDB 的默认端口为 8529）
• ARANGO_DB - 数据库名称
• ARANGO_USERNAME - 数据库用户
• ARANGO_PASSWORD - 数据库密码
• ARANGO_BACKUP_ROOT - arango_backup 输出的可选根目录。默认为 ./backups。

用法

你几乎可以提供任何有意义的提示词，Claude 都会尝试执行相应的函数。

一些提示词示例：

• “列出数据库中的所有集合”
• “查询所有用户”
• “在 users 集合中插入一条新文档，名称为 'John Doe'，邮箱为 "[email protected]'”
• “将键为 '123456' 或名称为 'Jane Doe' 的文档年龄改为 48”
• “创建名为 'products' 的新集合”

在 Claude App 中使用

与 Cline VSCode 扩展搭配使用

查询所有用户：

{
  "query": "FOR user IN users RETURN user",
  "limit": 100
}

插入新文档：

{
  "collection": "users",
  "document": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

更新文档：

{
  "collection": "users",
  "key": "123456",
  "update": {
    "name": "Jane Doe"
  }
}

删除文档：

{
  "collection": "users",
  "key": "123456"
}

列出所有集合：

{
} // No parameters required

备份数据库集合：

{
  "outputDir": "nightly_1", // Safe subdirectory name under ARANGO_BACKUP_ROOT. Absolute paths and slashes are rejected.
  "collection": "users", // Optional. If omitted, all collections are backed up.
  "docLimit": 1000 // Optional. Maximum documents per collection. Defaults to 1000 and is capped at 10000.
}

设置 ARANGO_BACKUP_ROOT，以选择备份存储位置。为降低任意文件写入风险，服务会拒绝路径遍历、绝对路径、符号链接逃逸以及已存在的输出文件。

创建新集合：

{
  "name": "products",
  "type": "document", // "document" or "edge" (optional, defaults to "document")
  "waitForSync": false // Optional, defaults to false
}

删除集合：

{
  "name": "products",
  "confirm": true
}

注意：该服务不依赖数据库结构，只要遵循 ArangoDB 的文档集合和边集合模型，就能与任意集合名称或结构配合使用。

免责声明

仅供开发使用

此工具仅面向本地开发环境。虽然从技术上讲它可以连接到生产数据库，但这会带来重大的安全风险，因此明确不建议这样做。我们仅将它用于开发数据库，以保持职责分离并保护生产数据。

开发

欢迎贡献。提交拉取请求前，请阅读 CONTRIBUTING.md。

1. 克隆仓库

2. 安装依赖：

   npm run build
   

3. 自动重建模式下进行开发：

   npm run watch
   

调试

由于 MCP 服务通过标准输入输出进行通信，调试可能颇具挑战。推荐在开发时使用 MCP Inspector 进行调试：

npm run inspector

Inspector 会提供一个 URL，供你在浏览器中访问调试工具。

测试

npm test

测试套件包含对 arango_backup 路径处理的回归测试，以防止绝对路径、路径遍历和符号链接逃逸。

要使用本地 Docker ArangoDB 实例运行集成冒烟测试：

npm run test:integration

集成测试会启动一个临时 Docker ArangoDB 实例，通过标准输入输出启动 MCP 服务，列出工具，验证 outputSchema，创建临时集合，插入文档，使用 limit 执行查询，验证备份输出位于 ARANGO_BACKUP_ROOT 下，拒绝绝对备份路径，清理集合，并停止容器。

测试容器默认使用主机端口 18529，以避免与本地运行在 8529 上的 ArangoDB 冲突。如有需要，可通过 ARANGO_PORT 覆盖该端口。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。