Mcp Arangodb Async

io.github.PCfVW由 GitHub 账号 PCfVW 发布v0.5.4更新于 Oct 24, 2026

Async MCP server for ArangoDB: 46 tools for graphs, queries, and multi-tenancy.

发布方自己的服务:AsyncFlow

已验证STDIO仅桌面数据库数据与分析

概览

AI 生成的概览

一个本地 MCP 服务器,为 AI 助手提供 46 个工具,用于查询、修改和分析 ArangoDB 数据库,包括图和多租户。

可以做什么
执行 AQL 查询,构建、解释和剖析查询,查看数据库状态与集合,并在多个已配置数据库间切换会话焦点数据库、解析实际使用的数据库。插入、更新、删除和批量写入文档,创建集合,备份集合。创建、列出和删除索引,并按 JSON schema 校验文档与引用。创建命名图,添加顶点与边集合及边定义,添加顶点和边,遍历图并查找最短路径。备份、恢复和校验图,读取图统计信息。搜索和列出服务器自身的工具,切换工作流,卸载工具以节省上下文。
适用场景
适合需要让助手直接操作 ArangoDB 的场景:浏览集合、编写和调优 AQL、把数据建模为图(例如代码依赖分析),或在同一会话中管理多个数据库。面向已运行 ArangoDB 并希望以对话方式完成数据库工作的开发者和分析人员。
运行要求
以本地 Python 进程运行(需 Python 3.11+),从 PyPI 安装,并需要可通过网络访问的 ArangoDB 服务器。README 通过 MCP 主机配置中的环境变量 ARANGO_URL、ARANGO_DB、ARANGO_USERNAME 和 ARANGO_PASSWORD 设置连接;ArangoDB 本身建议用 Docker 运行。
安装前请注意
该服务器可以写入、更新和删除文档、集合与索引,并可恢复图,因此可能改动生产数据库。它需要数据库凭据(ARANGO_USERNAME 和 ARANGO_PASSWORD)并保存在主机配置文件中;建议使用专用的低权限用户而非 root 账户。备份与恢复应先在生产数据之外测试。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Mcp Arangodb Async,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

ArangoDB MCP Server for Python

[Python] [License] [MCP] [PyPI]

A production-ready Model Context Protocol (MCP) server exposing advanced ArangoDB operations to AI assistants like Claude Desktop and Augment Code. Features async-first Python architecture, comprehensive graph management, flexible content conversion (JSON, Markdown, YAML, Table), backup/restore functionality, and analytics capabilities.


Quick Links

📚 Documentation: https://github.com/PCfVW/mcp-arango-async/tree/master/docs

🚀 Quick Start: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/quickstart.md

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

🗄️ Multi-Tenancy Guide: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/multi-tenancy-guide.md

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

📖 Tools Reference: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/tools-reference.md

🎯 MCP Design Patterns: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/mcp-design-patterns.md

📝 Changelog: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/developer-guide/changelog.md

🐛 Issues: https://github.com/PCfVW/mcp-arango-async/issues


Features

  • ✅ 46 MCP Tools - Complete ArangoDB operations (queries, collections, indexes, graphs)
  • ✅ Multi-Tenancy - Work with multiple databases, environment switching, cross-database operations
  • ✅ MCP Design Patterns - Progressive discovery, context switching, tool unloading (98.7% token savings)
  • ✅ Graph Management - Create, traverse, backup/restore named graphs
  • ✅ Content Conversion - JSON, Markdown, YAML, and Table formats
  • ✅ Backup/Restore - Collection and graph-level backup with validation
  • ✅ Analytics - Query profiling, explain plans, graph statistics
  • ✅ Dual Transport - stdio (desktop clients) and HTTP (web/containerized)
  • ✅ Docker Support - Run in Docker for isolation and reproducibility
  • ✅ Production-Ready - Retry logic, graceful degradation, comprehensive error handling
  • ✅ Type-Safe - Pydantic validation for all tool arguments

Architecture

┌────────────────────┐      ┌─────────────────────┐       ┌──────────────────┐│   MCP Client       │      │  ArangoDB MCP       │       │   ArangoDB       ││ (Claude, Augment)  │─────▶│  Server (Python)    │─────▶│  (Docker)        ││                    │      │  • 46 Tools         │       │  • Multi-Model   ││                    │      │  • Multi-Tenancy    │       │  • Graph Engine  ││                    │      │  • Graph Mgmt       │       │  • AQL Engine    ││                    │      │  • MCP Patterns     │       │                  │└────────────────────┘      └─────────────────────┘       └──────────────────┘

Getting Started with ArangoDB

Prerequisites

  • Docker and Docker Compose installed
  • Python 3.11+ (for mcp-arangodb-async)

Step 1: Install ArangoDB

Create a docker-compose.yml file:

yaml
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

Create a .env file:

bash
# ArangoDB root passwordARANGO_ROOT_PASSWORD=changeme
# MCP Server connection settingsARANGO_URL=http://localhost:8529ARANGO_DB=mcp_arangodb_testARANGO_USERNAME=mcp_arangodb_userARANGO_PASSWORD=mcp_arangodb_password

Start ArangoDB:

bash
docker compose --env-file .env up -d

Step 2: Install mcp-arangodb-async

Install the MCP server package:

bash
pip install mcp-arangodb-async
Alternative: Install with Conda/Mamba/Micromamba
bash
# Create environment and installconda create -n mcp-arango python=3.11conda activate mcp-arangopip 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
Alternative: Install with uv
bash
# Create environment and installuv venv .venv --python 3.11uv pip install mcp-arangodb-async

Step 3: Create Database and User

Create the database and user for the MCP server:

bash
maa db add mcp_arangodb_test \  --url http://localhost:8529 \  --with-user mcp_arangodb_user \  --env-file .env

Expected output:

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]: ydb add:[ADDED] Database 'mcp_arangodb_test'[ADDED] User 'mcp_arangodb_user' (active: true)[GRANTED] Permission rw: mcp_arangodb_user → mcp_arangodb_test

Verify the database connection:

bash
# Set environment variablesexport ARANGO_URL=http://localhost:8529export ARANGO_DB=mcp_arangodb_testexport ARANGO_USERNAME=mcp_arangodb_userexport ARANGO_PASSWORD=mcp_arangodb_password
# Run health checkmaa health

Expected output:

json
{"status": "healthy", "database_connected": true, "database_info": {"version": "3.11.x", "name": "mcp_arangodb_test"}}

Step 4: Configure MCP Host

Configure your MCP host to use the server. The configuration includes environment variables for database connection. The location of the configuration file depends on your MCP host. For Claude Desktop, the file is located at:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

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"      }    }  }}
Alternative: Configuration for Conda/Mamba/Micromamba

If you installed with conda/mamba/micromamba, use the run command:

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

Replace "conda" with "mamba" or "micromamba" if using those tools.

Alternative: Configuration for uv

If you installed with uv, use 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"      }    }  }}

Replace /path/to/project with the directory containing your .venv folder.

Restart your MCP client after updating the configuration.

Test the connection:

Ask your MCP client: "List all collections in the ArangoDB database"

The assistant should successfully connect and list your collections.

Available Tools

The server exposes 46 MCP tools organized into 11 categories:

Multi-Tenancy Tools (4 tools)

  • arango_set_focused_database - Set focused database for session
  • arango_get_focused_database - Get currently focused database
  • arango_list_available_databases - List all configured databases
  • arango_get_database_resolution - Show database resolution algorithm

Core Data Operations (7 tools)

  • arango_query - Execute AQL queries
  • arango_list_collections - List all collections
  • arango_insert - Insert documents
  • arango_update - Update documents
  • arango_remove - Remove documents
  • arango_create_collection - Create collections
  • arango_backup - Backup collections

Index Management (3 tools)

  • arango_list_indexes - List indexes
  • arango_create_index - Create indexes
  • arango_delete_index - Delete indexes

Query Analysis (3 tools)

  • arango_explain_query - Explain query execution plan
  • arango_query_builder - Build AQL queries
  • arango_query_profile - Profile query performance

Data Validation (4 tools)

  • arango_validate_references - Validate document references
  • arango_insert_with_validation - Insert with validation
  • arango_create_schema - Create JSON schemas
  • arango_validate_document - Validate against schema

Bulk Operations (2 tools)

  • arango_bulk_insert - Bulk insert documents
  • arango_bulk_update - Bulk update documents

Graph Management (7 tools)

  • arango_create_graph - Create named graphs
  • arango_list_graphs - List all graphs
  • arango_add_vertex_collection - Add vertex collections
  • arango_add_edge_definition - Add edge definitions
  • arango_add_vertex - Add vertices
  • arango_add_edge - Add edges
  • arango_graph_traversal - Traverse graphs

Graph Traversal (2 tools)

  • arango_traverse - Graph traversal
  • arango_shortest_path - Find shortest paths

Graph Backup/Restore (5 tools)

  • arango_backup_graph - Backup single graph
  • arango_restore_graph - Restore single graph
  • arango_backup_named_graphs - Backup all named graphs
  • arango_validate_graph_integrity - Validate graph integrity
  • arango_graph_statistics - Graph statistics

Health & Status (1 tool)

  • arango_database_status - Get comprehensive status of all databases

Tool Aliases (2 tools)

  • arango_graph_traversal - Alias for arango_traverse
  • arango_add_vertex - Alias for arango_insert

MCP Design Pattern Tools (8 tools)

  • arango_search_tools - Search for tools by keywords
  • arango_list_tools_by_category - List tools by category
  • arango_switch_workflow - Switch workflow context
  • arango_get_active_workflow - Get active workflow
  • arango_list_workflows - List all workflows
  • arango_advance_workflow_stage - Advance workflow stage
  • arango_get_tool_usage_stats - Get tool usage statistics
  • arango_unload_tools - Unload specific tools

📖 Complete tools reference: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/tools-reference.md

📖 MCP Design Patterns Guide: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/mcp-design-patterns.md


Use Case Example: Codebase Graph Analysis

Model your codebase as a graph to analyze dependencies, find circular references, and understand architecture. Here is an excerpt from the longer codebase analysis example:

python
# 1. Create graph structureAsk Claude: "Create a graph called 'codebase' with vertex collections 'modules' and 'functions', and edge collection 'calls' connecting functions"
# 2. Import codebase dataAsk Claude: "Insert these modules into the 'modules' collection: [...]"
# 3. Analyze dependenciesAsk Claude: "Find all functions that depend on the 'auth' module using graph traversal"
# 4. Detect circular dependenciesAsk Claude: "Check for circular dependencies in the codebase graph"
# 5. Generate architecture diagramAsk Claude: "Export the codebase graph structure as Markdown for visualization"

📖 More examples


Documentation

Getting Started

Configuration

User Guide

Developer Guide

Examples

📖 Full documentation: https://github.com/PCfVW/mcp-arango-async/tree/master/docs


Troubleshooting

Common Issues

Database connection fails:

bash
# Check ArangoDB is runningdocker ps | grep arangodb
# Test connectioncurl http://localhost:8529/_api/version
# Check credentialsmaa health

Server won't start in Claude Desktop:

bash
# Verify Python installationpython --version  # Must be 3.11+
# Test module directlymaa health
# Check Claude Desktop logs# Windows: %APPDATA%\Claude\logs\# macOS: ~/Library/Logs/Claude/

Tool execution errors:

  • Verify ArangoDB is healthy: docker compose ps
  • Check environment variables are set correctly
  • Review server logs for detailed error messages

📖 Complete troubleshooting guide


Why Docker for ArangoDB?

✅ Stability - Isolated environment, no host conflicts
✅ Zero-install - Start/stop with docker compose
✅ Reproducibility - Same image across all environments
✅ Health checks - Built-in readiness validation
✅ Fast reset - Recreate clean instances easily
✅ Portability - Consistent on Windows/macOS/Linux


License

  • This project: Apache License 2.0
  • ArangoDB 3.11: Apache License 2.0
  • ArangoDB 3.12+: Business Source License 1.1 (BUSL-1.1)

⚠️ Important: This repository does not grant rights to ArangoDB binaries. You must comply with ArangoDB's license for your deployment version.

📖 License details


Contributing

Contributions are welcome! Please see our documentation for guidelines.

📖 Architecture decisions


Support


Acknowledgments

Built with:

来源:README.md,提交 63b22f5

工具

0
SourceWeft 尚未在沙箱中启动过该软件包,因此其工具未知。

版本历史

1
  1. v0.5.4最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分

其他 Async 集成