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 整合