ArangoDB MCP Server for Python

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-stdio.md

🔧 Installation: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/installation.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

✅ 43 MCP Tools - Complete ArangoDB operations (queries, collections, indexes, graphs) ✅ 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)        │
│                    │      │  • 43 Tools         │       │  • Multi-Model   │
│                    │      │  • Graph Mgmt       │       │  • Graph Engine  │
│                    │      │  • MCP Patterns     │       │  • AQL Engine    │
└────────────────────┘      └─────────────────────┘       └──────────────────┘

Installation

Prerequisites

Python 3.11+
Docker Desktop (for ArangoDB)

Quick Install

# Install from PyPI
pip install mcp-arangodb-async

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

# Verify installation
python -m mcp_arangodb_async --health

Expected output:

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

📖 Detailed installation guide: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/installation.md

Quick Start

stdio Transport (Desktop Clients)

1. Configure Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/.config/Claude/claude_desktop_config.json (macOS/Linux):

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

2. Restart Claude Desktop

3. Test the connection:

Ask Claude: "List all collections in the ArangoDB database"

📖 Full stdio quickstart: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/quickstart-stdio.md

Docker Container (Alternative)

1. Build the Docker image:

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

2. Configure Claude Desktop:

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/.config/Claude/claude_desktop_config.json (macOS/Linux):

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

3. Restart Claude Desktop

📖 Transport configuration guide: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/configuration/transport-configuration.md

HTTP Transport (Web/Containerized)

1. Start HTTP server:

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

2. Test health endpoint:

curl http://localhost:8000/health

3. Connect from web client:

import { MCPClient } from '@modelcontextprotocol/sdk';

const client = new MCPClient({
  transport: 'http',
  url: 'http://localhost:8000/mcp'
});

await client.connect();
const tools = await client.listTools();

📖 HTTP transport guide: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/developer-guide/http-transport.md

Configuration

Environment Variables

Required:

ARANGO_URL=http://localhost:8529
ARANGO_DB=mcp_arangodb_test
ARANGO_USERNAME=root
ARANGO_PASSWORD=changeme

Optional:

# Transport configuration
MCP_TRANSPORT=stdio                    # stdio or http
MCP_HTTP_HOST=0.0.0.0                  # HTTP bind address
MCP_HTTP_PORT=8000                     # HTTP port
MCP_HTTP_STATELESS=false               # Stateless mode

# Connection tuning
ARANGO_TIMEOUT_SEC=30.0                # Request timeout
ARANGO_CONNECT_RETRIES=3               # Connection retries
ARANGO_CONNECT_DELAY_SEC=1.0           # Retry delay

# Logging
LOG_LEVEL=INFO                         # DEBUG, INFO, WARNING, ERROR

📖 Complete configuration reference: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/configuration/environment-variables.md

Available Tools

The server exposes 43 MCP tools organized into 10 categories:

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 (4 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

Analytics (2 tools)

arango_graph_statistics - Graph statistics
arango_database_status - Database status

MCP Design Pattern Tools (9 tools)

arango_search_tools - Search for tools by keywords
arango_list_tools_by_category - List tools by category
arango_switch_context - Switch workflow context
arango_get_active_context - Get active context
arango_list_contexts - List all contexts
arango_advance_workflow_stage - Advance workflow stage
arango_get_tool_usage_stats - Get tool usage statistics
arango_unload_tools - Unload specific tools
arango_graph_traversal - Alias for arango_traverse

📖 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:

# 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: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/examples/codebase-analysis.md

Documentation

Getting Started

Configuration

User Guide

Developer Guide

Examples

Codebase Dependency Analysis

📖 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
python -m mcp_arangodb_async --health

Server won't start in Claude Desktop:

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

# Test module directly
python -m mcp_arangodb_async --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: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/troubleshooting.md

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: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/installation.md#arangodb-licensing

Contributing

Contributions are welcome! Please see our documentation for guidelines.

📖 Architecture decisions: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/developer-guide/low-level-mcp-rationale.md

Support

Issues: https://github.com/PCfVW/mcp-arango-async/issues
Discussions: https://github.com/PCfVW/mcp-arango-async/discussions
Documentation: https://github.com/PCfVW/mcp-arango-async/tree/master/docs

Acknowledgments

Built with:

Model Context Protocol by Anthropic
python-arango - Official ArangoDB Python driver
Pydantic - Data validation
Starlette - HTTP transport
ArangoDB - Multi-model database

Name		Name	Last commit message	Last commit date
Latest commit History 42 Commits
.github/workflows		.github/workflows
docs		docs
mcp_arangodb_async		mcp_arangodb_async
scripts		scripts
tests		tests
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
env.example		env.example
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt

PCfVW/mcp-arangodb-async

Folders and files

Latest commit

History

Repository files navigation

ArangoDB MCP Server for Python

Quick Links

Features

Architecture

Installation

Prerequisites

Quick Install

Quick Start

stdio Transport (Desktop Clients)

Docker Container (Alternative)

HTTP Transport (Web/Containerized)

Configuration

Environment Variables

Available Tools

Core Data Operations (7 tools)

Index Management (3 tools)

Query Analysis (3 tools)

Data Validation (4 tools)

Bulk Operations (2 tools)

Graph Management (7 tools)

Graph Traversal (2 tools)

Graph Backup/Restore (4 tools)

Analytics (2 tools)

MCP Design Pattern Tools (9 tools)

Use Case Example: Codebase Graph Analysis

Documentation

Getting Started

Configuration

User Guide

Developer Guide

Examples

Troubleshooting

Common Issues

Why Docker for ArangoDB?

License

Contributing

Support

Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages