Mcp Arangodb Async

io.github.PCfVWPublished by GitHub account PCfVWv0.5.4Updated Oct 24, 2026

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

The publisher's own server: AsyncFlow

VerifiedSTDIODesktop onlyDatabasesData & Analytics

Overview

AI-generated overview

A local MCP server that gives an AI assistant 46 tools to query, modify, and analyze an ArangoDB database, including graphs and multi-tenancy.

What you can do
Run AQL queries, build, explain and profile them, and inspect database status and collections across configured databases, including switching the focused database for a session and resolving which database is used. Insert, update, remove and bulk-load documents, create collections, and back up collections. Create, list and delete indexes, and validate documents and references against JSON schemas. Create named graphs, add vertex and edge collections and definitions, add vertices and edges, traverse graphs and find shortest paths. Back up, restore and validate graphs, and read graph statistics. Search and list the server's own tools, switch workflows, and unload tools to save context.
When to use it
Useful when an assistant needs to work directly with an ArangoDB instance: exploring collections, writing and tuning AQL, modeling data as graphs such as code dependencies, or managing several databases from one session. It is aimed at developers and analysts who already run ArangoDB and want database work done conversationally.
Requirements
Runs as a local Python process (Python 3.11+) installed from PyPI, with an ArangoDB server reachable over the network. The README configures the connection through environment variables ARANGO_URL, ARANGO_DB, ARANGO_USERNAME and ARANGO_PASSWORD in the MCP host configuration; Docker is suggested for running ArangoDB itself.
Before you install
The server can write, update and delete documents, collections and indexes, and restore graphs, so changes to a live database are possible. It needs database credentials (ARANGO_USERNAME and ARANGO_PASSWORD) stored in the host configuration file; use a dedicated low-privilege user rather than the root account. Backups and restores should be tested on non-production data first.

Installation

In SourceWeft

  1. Open Mcp Arangodb Async in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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:

Source: README.md at commit 63b22f5

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.5.4LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Async integrations