ArangoDB 的 MCP 服务器

这是一个基于 TypeScript 的 MCP 服务器，通过 ArangoDB 提供数据库交互功能。它实现了核心数据库操作，并允许通过 MCP 工具无缝集成到 ArangoDB 中。您可以将其与 Claude 应用程序一起使用，也可以用于与 MCP 兼容的 VSCode 扩展，如 Cline！

功能

工具

• arango_query - 执行 AQL 查询

  • 需要一个 AQL 查询字符串作为参数
  • 可选地接受绑定变量以支持参数化查询
  • 返回查询结果为 JSON 格式

• arango_insert - 向集合中插入文档

  • 需要集合名称和文档对象作为参数
  • 如果未提供文档键，则会自动生成
  • 返回创建的文档元数据

• arango_update - 更新现有文档

  • 需要集合名称、文档键和更新对象作为参数
  • 返回更新后的文档元数据

• arango_remove - 从集合中移除文档

  • 需要集合名称和文档键作为参数
  • 返回移除的文档元数据

• arango_backup - 将所有集合备份到 JSON 文件

  • 需要输出目录路径作为参数
  • 为每个集合创建包含当前数据的 JSON 文件
  • 对于数据备份和迁移非常有用

• arango_list_collections - 列出数据库中的所有集合

  • 返回集合信息数组，包括名称、ID 和类型

• arango_create_collection - 在数据库中创建新集合

  • 需要集合名称作为参数
  • 可选地指定集合类型（文档或边集合）
  • 配置写操作的 waitForSync 行为
  • 返回集合信息，包括名称、类型和状态

安装

通过 NPM 安装

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

npm install -g arango-server

通过 NPX 运行

要在不进行安装的情况下直接运行 arango-server，使用以下命令：

npx arango-server

配置 VSCode 代理

要将 arango-server 与 VSCode Copilot 代理一起使用，您必须至少安装了 VSCode 1.99.0 并遵循以下步骤：

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

   • 工作区特定配置：在您的工作区中创建或编辑 .vscode/mcp.json 文件。

   • 用户特定配置：可选地，在 设置(mcp) VS Code 用户设置中指定服务器，以便在所有工作区中启用 MCP 服务器。

     提示：您可以参考 这里 的 VSCode MCP 配置文档，了解如何设置配置文件的更多细节。

2. 添加以下配置：

   {
   	"servers": {
   		"arango-mcp": {
   			"type": "stdio",
   			"command": "npx",
   			"args": ["arango-server"],
   			"env": {
   				"ARANGO_URL": "http://localhost:8529",
   				"ARANGO_DB": "v20",
   				"ARANGO_USERNAME": "app",
   				"ARANGO_PASSWORD": "75Sab@MYa3Dj8Fc"
   			}
   		}
   	}
   }
   

3. 启动 MCP 服务器：

   • 在 VSCode 中打开命令面板 (Ctrl+Shift+P 或 Mac 上的 Cmd+Shift+P)。
   • 运行命令 MCP: Start Server 并从列表中选择 arango-mcp。

4. 验证服务器：

   • 在 VSCode 中打开聊天视图并切换到代理模式。
   • 使用 工具 按钮验证 arango-server 工具是否可用。

通过 Smithery 安装

要通过 Smithery 自动安装 ArangoDB for Claude Desktop：

npx -y @smithery/cli install @ravenwits/mcp-server-arangodb --client claude

与 Claude Desktop 一起使用

前往：设置 > 开发者 > 编辑配置 或

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

与 Cline VSCode 扩展一起使用

前往：Cline 扩展 > MCP 服务器 > 编辑配置 或

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

在 mcpServers 部分添加以下配置：

{
	"mcpServers": {
		"arango": {
			"command": "node",
			"args": ["/path/to/arango-server/build/index.js"],
			"env": {
				"ARANGO_URL": "your_database_url",
				"ARANGO_DB": "your_database_name",
				"ARANGO_USERNAME": "your_username",
				"ARANGO_PASSWORD": "your_password"
			}
		}
	}
}

环境变量

该服务器需要以下环境变量：

• ARANGO_URL - ArangoDB 服务器 URL（注意：8529 是 ArangoDB 的默认端口，适用于本地开发）
• ARANGO_DB - 数据库名称
• ARANGO_USERNAME - 数据库用户名
• ARANGO_PASSWORD - 数据库密码

使用方法

您可以提供任何有意义的提示，Claude 将尝试执行相应的函数。

一些示例提示：

• "列出数据库中的所有集合"
• "查询所有用户"
• "向 'users' 集合中插入一个新文档，名字为 'John Doe'，邮箱为 'john@example.com'"
• "更新具有键 '123456' 或名字 'Jane Doe' 的文档，更改年龄为 48"
• "创建一个名为 'products' 的新集合"

与 Claude 应用程序一起使用

与 Cline VSCode 扩展一起使用

查询所有用户：

{
  "query": "FOR user IN users RETURN user"
}

插入一个新文档：

{
  "collection": "users",
  "document": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

更新一个文档：

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

移除一个文档：

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

列出所有集合：

{
} // 不需要参数

备份数据库集合：

{
  "outputDir": "./backup" // 指定备份文件的绝对输出目录路径（可选）
  "collection": "users" // 指定要备份的集合名称（可选）如果没有提供集合名称，则会备份所有集合
  "docLimit": 1000 // 指定每个集合要备份的最大文档数（可选），如果没有提供，则会备份所有文档（没有限制可能会导致大型集合超时）
}

创建一个新集合：

{
  "name": "products",
  "type": "document", // "document" 或 "edge"（可选，默认为 "document"）
  "waitForSync": false // 可选，默认为 false
}

注意：该服务器是数据库结构无关的，可以与任何集合名称或结构一起工作，只要它们遵循 ArangoDB 的文档和边集合模型。

声明

仅用于开发

此工具仅设计用于本地开发环境。虽然从技术上讲它可以连接到生产数据库，但这会产生重大的安全风险，并且明确禁止这样做。我们仅使用开发数据库来维护职责分离并保护生产数据。

开发

1. 克隆仓库

2. 安装依赖项：

   npm run build
   

3. 开发时自动重建：

   npm run watch
   

调试

由于 MCP 服务器通过 stdio 通信，调试可能具有挑战性。推荐使用 MCP Inspector 进行开发调试：

npm run inspector

Inspector 将提供一个 URL，您可以在浏览器中访问调试工具。

许可证

本项目根据 MIT 许可证发布 - 详情见 LICENSE 文件。