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 文件。

   • 用户特定配置：可选地，在 setting(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 中打开聊天视图并切换到代理模式。
   • 使用 Tools 按钮验证 arango-server 工具是否可用。

通过 Smithery 安装

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

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

与 Claude Desktop 一起使用

前往：Settings > Developer > Edit Config 或

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

与 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": "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 将尝试执行相应的功能。

一些示例提示：

• "列出数据库中的所有集合"
• "查询所有用户"
• "将名为 'John Doe' 且电子邮件为 'john@example.com' 的新文档插入 'users' 集合"
• "更新键为 '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 文件。