Skip to main content
Glama
mcp-arangodb-async

mcp-arangodb-async

by PCfVW

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.


πŸ“š 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


Related MCP server: production-grade-mcp-agentic-system

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:

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:

# ArangoDB root password
ARANGO_ROOT_PASSWORD=changeme

# MCP Server connection settings
ARANGO_URL=http://localhost:8529
ARANGO_DB=mcp_arangodb_test
ARANGO_USERNAME=mcp_arangodb_user
ARANGO_PASSWORD=mcp_arangodb_password

Start ArangoDB:

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

Step 2: Install mcp-arangodb-async

Install the MCP server package:

pip install mcp-arangodb-async
# Create environment and install
conda create -n mcp-arango python=3.11
conda activate mcp-arango
pip 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
# Create environment and install
uv venv .venv --python 3.11
uv pip install mcp-arangodb-async

Step 3: Create Database and User

Create the database and user for the MCP server:

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]: y
db 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:

# Set environment variables
export ARANGO_URL=http://localhost:8529
export ARANGO_DB=mcp_arangodb_test
export ARANGO_USERNAME=mcp_arangodb_user
export ARANGO_PASSWORD=mcp_arangodb_password

# Run health check
maa health

Expected output:

{"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:

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

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

{
  "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.

If you installed with uv, use uv run:

{
  "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:

# 1. Create graph structure
Ask Claude: "Create a graph called 'codebase' with vertex collections 'modules' and 'functions', and edge collection 'calls' connecting functions"

# 2. Import codebase data
Ask Claude: "Insert these modules into the 'modules' collection: [...]"

# 3. Analyze dependencies
Ask Claude: "Find all functions that depend on the 'auth' module using graph traversal"

# 4. Detect circular dependencies
Ask Claude: "Check for circular dependencies in the codebase graph"

# 5. Generate architecture diagram
Ask 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:

# Check ArangoDB is running
docker ps | grep arangodb

# Test connection
curl http://localhost:8529/_api/version

# Check credentials
maa health

Server won't start in Claude Desktop:

# Verify Python installation
python --version  # Must be 3.11+

# Test module directly
maa 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:

Available Tools

46 tools
arango_add_edgeC

Add an edge document between two vertices with optional attributes.

Inputs: collection (required), from_id (required), to_id (required), attributes, +1 more.

arango_add_edge_definitionC

Create an edge definition in a named graph.

Inputs: graph (required), edge_collection (required), from_collections (required), to_collections (required), +1 more.

arango_add_vertexC

Alias for arango_insert (insert a vertex document into a collection).

Inputs: collection (required), document (required), database.

arango_add_vertex_collectionC

Add a vertex collection to a named graph.

Inputs: graph (required), collection (required), database.

arango_advance_workflow_stageB

Advance to the next workflow stage, automatically unloading tools from previous stage and loading tools for new stage. Enables Tool Unloading pattern.

Inputs: stage (required).

arango_backupC

Backup collections to JSON files.

Inputs: outputDir, collection, collections, docLimit, +1 more.

arango_backup_graphB

Export complete graph structure including vertices, edges, and metadata.

Inputs: graph_name (required), outputDir, includeMetadata, docLimit, +1 more.

arango_backup_named_graphsC

Backup graph definitions from _graphs system collection.

Inputs: outputFile, graphNames, database.

arango_bulk_insertC

Bulk insert documents with batching and basic error handling.

Inputs: collection (required), documents (required), validate_refs, batch_size, +2 more.

arango_bulk_updateC

Bulk update documents by key with batching.

Inputs: collection (required), updates (required), batch_size, on_error, +1 more.

arango_create_collectionC

Create a collection (document or edge).

Inputs: name (required), type, waitForSync, database.

arango_create_graphB

Create a named graph with edge definitions (optionally creating collections).

Inputs: name (required), edge_definitions (required), create_collections, database.

arango_create_indexB

Create an index on a collection (persistent, hash, skiplist, ttl, fulltext, geo).

Inputs: collection (required), fields (required), type, unique, +9 more.

arango_create_schemaC

Create or update a named JSON Schema for a collection.

Inputs: name (required), collection (required), schema (required), database.

arango_database_statusB

Get connection status for all configured databases, showing which databases are accessible, their versions, and which database is currently focused.

Inputs: database.

arango_delete_indexB

Delete an index by id or name from a collection.

Inputs: collection (required), id_or_name (required), database.

arango_explain_queryA

Explain an AQL query and return execution plans and optional index suggestions.

Inputs: query (required), bind_vars, suggest_indexes, max_plans, +1 more.

arango_get_active_workflowA

Get the currently active workflow context and its tool set.

Inputs: no named parameters.

arango_get_database_resolutionA

Show the database resolution algorithm result for the current session, displaying which database would be used based on the 6-level priority fallback.

Inputs: no named parameters.

arango_get_focused_databaseA

Get the currently focused database for the current session.

Inputs: no named parameters.

arango_get_tool_usage_statsA

Get usage statistics for all tools, including use counts and last used timestamps. Useful for understanding tool usage patterns.

Inputs: no named parameters.

arango_graph_statisticsA

Generate comprehensive graph analytics (vertex/edge counts, degree distribution, connectivity metrics).

Inputs: graphName, includeDegreeDistribution, includeConnectivity, sampleSize, +3 more.

arango_graph_traversalC

Alias for arango_traverse (graph traversal by graph or edge collections).

Inputs: start_vertex (required), direction, min_depth, max_depth, +5 more.

arango_insertC

Insert a document into a collection.

Inputs: collection (required), document (required), database.

arango_insert_with_validationC

Insert a document after validating its reference fields.

Inputs: collection (required), document (required), reference_fields, database.

arango_list_available_databasesA

List all configured databases available for multi-tenancy operations.

Inputs: no named parameters.

arango_list_collectionsB

List non-system collection names.

Inputs: database.

arango_list_graphsB

List available graphs in the database.

Inputs: database.

arango_list_indexesB

List indexes for a collection.

Inputs: collection (required), database.

arango_list_tools_by_categoryA

List all MCP tools organized by category. Useful for understanding tool organization and selecting workflow-specific tool sets.

Inputs: category.

arango_list_workflowsB

List all available workflow contexts with their descriptions and optional tool lists.

Inputs: include_tools.

arango_queryC

Execute an AQL query with optional bind vars and return rows.

Inputs: query (required), bind_vars, database.

arango_query_builderB

Build and execute a simple AQL query from filters, sort, and limit.

Inputs: collection (required), filters, sort, limit, +2 more.

arango_query_profileC

Explain a query and return plans/stats for profiling.

Inputs: query (required), bind_vars, max_plans, database.

arango_removeB

Remove a document by key in a collection.

Inputs: collection (required), key (required), database.

arango_restore_graphC

Import graph data with referential integrity validation and conflict resolution.

Inputs: inputDir (required), graphName, conflictResolution, validateIntegrity, +1 more.

arango_search_toolsA

Search for MCP tools by keywords and categories. Enables progressive tool discovery by returning only relevant tools instead of loading all 34 tools upfront.

Inputs: keywords (required), categories, detail_level.

arango_set_focused_databaseA

Set the focused database for the current session. All subsequent tool calls will use this database unless overridden with the database parameter. Pass None or empty string to unset the focused database and revert to default database resolution.

Inputs: database.

arango_shortest_pathC

Compute the shortest path between two vertices (by graph or edge collections).

Inputs: start_vertex (required), end_vertex (required), direction, graph, +3 more.

arango_switch_workflowA

Switch to a different workflow context with a predefined set of tools. Enables Workflow Switching pattern for workflow-specific tool sets.

Inputs: context (required).

arango_traverseC

Traverse graph from a start vertex with depth bounds (by graph or edge collections).

Inputs: start_vertex (required), direction, min_depth, max_depth, +5 more.

arango_unload_toolsA

Manually unload specific tools from the active context. Useful for fine-grained control over tool lifecycle.

Inputs: tool_names (required).

arango_updateB

Update a document by key in a collection.

Inputs: collection (required), key (required), update (required), database.

arango_validate_documentC

Validate a document against a stored or inline JSON Schema.

Inputs: collection (required), document (required), schema_name, schema, +1 more.

arango_validate_graph_integrityC

Verify graph consistency, orphaned edges, and constraint violations.

Inputs: graphName, checkOrphanedEdges, checkConstraints, returnDetails, +1 more.

arango_validate_referencesB

Validate that documents in a collection have valid references in specified fields.

Inputs: collection (required), reference_fields (required), fix_invalid, database.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 46 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but several aliases (e.g., arango_add_vertex as alias for arango_insert, arango_graph_traversal as alias for arango_traverse) create potential confusion, as an agent may select the wrong tool if unaware of the alias.

    Naming Consistency4/5

    The majority of tools follow a consistent arango_verb_noun pattern. However, minor inconsistencies exist, such as mixing 'add' and 'create' (e.g., arango_add_edge vs arango_create_collection) and using noun_noun for arango_query_builder.

    Tool Count2/5

    With 46 tools, the server has significantly more than the ideal range. While the domain is broad, many tools are workflow management or backup-related, and the presence of aliases adds redundancy, making tool selection more complex.

    Completeness4/5

    The tool set covers a wide range of ArangoDB operations including CRUD, graph management, indexing, schema validation, querying, backup/restore, and multi-tenancy. Minor gaps like lack of transaction support are acceptable for an MCP server.

    Maintenance

    ActivityNo data
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers