Production-ready MCP server providing advanced ArangoDB operations for AI assistants with asynchronous Python architecture, comprehensive graph management, flexible content conversion, backup/restore functionality, and analytics capabilities.

Installation

PyPI

pip install mcp-arangodb-async

Docker Setup

docker run -d \
  --name arangodb \
  -p 8529:8529 \
  -e ARANGO_ROOT_PASSWORD=changeme \
  arangodb:3.11

Health Check

python -m mcp_arangodb_async --health

Build Docker Container

docker build -t mcp-arangodb-async:latest .

HTTP Server

python -m mcp_arangodb_async --transport http --host 0.0.0.0 --port 8000

Configuration

Claude Desktop (stdio)

{
  "mcpServers": {
    "arangodb": {
      "command": "python",
      "args": ["-m", "mcp_arangodb_async", "server"],
      "env": {
        "ARANGO_URL": "http://localhost:8529",
        "ARANGO_DB": "mcp_arangodb_test",
        "ARANGO_USERNAME": "mcp_arangodb_user",
        "ARANGO_PASSWORD": "mcp_arangodb_password"
      }
    }
  }
}

Claude Desktop (Docker)

{
  "mcpServers": {
    "arangodb": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp-arangodb-async:latest"],
      "env": {
        "ARANGO_URL": "http://host.docker.internal:8529",
        "ARANGO_DB": "mcp_arangodb_test",
        "ARANGO_USERNAME": "mcp_arangodb_user",
        "ARANGO_PASSWORD": "mcp_arangodb_password"
      }
    }
  }
}

Available Tools

Tool	Description
arango_query	Execute AQL queries
arango_list_collections	List all collections
arango_insert	Insert documents
arango_update	Update documents
arango_remove	Delete documents
arango_create_collection	Create collections
arango_backup	Backup collections
arango_list_indexes	List indexes
arango_create_index	Create indexes
arango_delete_index	Delete indexes
arango_explain_query	Explain query execution plan
arango_query_builder	Build AQL queries
arango_query_profile	Profile query performance
arango_validate_references	Validate document references
arango_insert_with_validation	Insert with validation

Features

• 43 MCP tools - Complete ArangoDB operations (queries, collections, indexes, graphs)
• MCP design patterns - Progressive discovery, context switching, tool offloading (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 backups 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

Environment Variables

Required

• ARANGO_URL - ArangoDB connection URL
• ARANGO_DB - Database name
• ARANGO_USERNAME - Database username
• ARANGO_PASSWORD - Database password

Optional

• MCP_TRANSPORT - Transport type (stdio or http)
• MCP_HTTP_HOST - HTTP bind address
• MCP_HTTP_PORT - HTTP port
• MCP_HTTP_STATELESS - Stateless mode
• ARANGO_TIMEOUT_SEC - Request timeout
• ARANGO_CONNECT_RETRIES - Connection retries
• ARANGO_CONNECT_DELAY_SEC - Retry delay
• LOG_LEVEL - Log level (DEBUG, INFO, WARNING, ERROR)

Usage Examples

Show all collections in the ArangoDB database

Create a graph named 'codebase' with vertex collections 'modules' and 'functions', and an edge collection 'calls' connecting functions

Insert these modules into the 'modules' collection

Find all functions that depend on the 'auth' module using graph traversal

Check for circular dependencies in the codebase graph

Notes

Requires Python 3.11+ and Docker Desktop for ArangoDB. The server provides comprehensive graph analysis capabilities, including codebase dependency analysis, circular reference detection, and architecture visualization. Supports both stdio and HTTP transports for various deployment scenarios.