mcp-arangodb-async
Provides tools for interacting with ArangoDB, enabling AI agents to manage collections, execute AQL queries, perform graph operations, backup/restore data, and analyze query performance.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-arangodb-async query for active users in the 'orders' collection"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.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: localCreate 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_passwordStart ArangoDB:
docker compose --env-file .env up -dStep 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-asyncStep 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 .envExpected 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_testVerify 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 healthExpected 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.jsonmacOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonLinux:
~/.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 sessionarango_get_focused_database- Get currently focused databasearango_list_available_databases- List all configured databasesarango_get_database_resolution- Show database resolution algorithm
Core Data Operations (7 tools)
arango_query- Execute AQL queriesarango_list_collections- List all collectionsarango_insert- Insert documentsarango_update- Update documentsarango_remove- Remove documentsarango_create_collection- Create collectionsarango_backup- Backup collections
Index Management (3 tools)
arango_list_indexes- List indexesarango_create_index- Create indexesarango_delete_index- Delete indexes
Query Analysis (3 tools)
arango_explain_query- Explain query execution planarango_query_builder- Build AQL queriesarango_query_profile- Profile query performance
Data Validation (4 tools)
arango_validate_references- Validate document referencesarango_insert_with_validation- Insert with validationarango_create_schema- Create JSON schemasarango_validate_document- Validate against schema
Bulk Operations (2 tools)
arango_bulk_insert- Bulk insert documentsarango_bulk_update- Bulk update documents
Graph Management (7 tools)
arango_create_graph- Create named graphsarango_list_graphs- List all graphsarango_add_vertex_collection- Add vertex collectionsarango_add_edge_definition- Add edge definitionsarango_add_vertex- Add verticesarango_add_edge- Add edgesarango_graph_traversal- Traverse graphs
Graph Traversal (2 tools)
arango_traverse- Graph traversalarango_shortest_path- Find shortest paths
Graph Backup/Restore (5 tools)
arango_backup_graph- Backup single grapharango_restore_graph- Restore single grapharango_backup_named_graphs- Backup all named graphsarango_validate_graph_integrity- Validate graph integrityarango_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_traversearango_add_vertex- Alias for arango_insert
MCP Design Pattern Tools (8 tools)
arango_search_tools- Search for tools by keywordsarango_list_tools_by_category- List tools by categoryarango_switch_workflow- Switch workflow contextarango_get_active_workflow- Get active workflowarango_list_workflows- List all workflowsarango_advance_workflow_stage- Advance workflow stagearango_get_tool_usage_stats- Get tool usage statisticsarango_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 healthServer 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 psCheck 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.
Support
Acknowledgments
Built with:
Model Context Protocol by Anthropic
python-arango - Official ArangoDB Python driver
Pydantic - Data validation
Starlette - HTTP transport
ArangoDB - Multi-model database
Available Tools
46 toolsarango_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
Scored across 46 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server that provides full integration with LightRAG API, offering 22 tools across document management, querying, knowledge graph operations, and system management.38MIT
- AlicenseNot gradedqualityDmaintenanceA production-grade MCP server designed for multi-tenant, authenticated, and observable AI agent systems, enabling secure tool execution across heterogeneous data sources.68MIT
- AlicenseBqualityDmaintenanceTurns ArangoDB into a schema-driven MCP server for agents, enabling search-describe-exec workflows for database, graph, and knowledge operations without oversizing the tool list.10MIT
- AlicenseNot gradedqualityDmaintenanceProduction-ready MCP server for MySQL databases enabling AI assistants to interact with MySQL through secure, validated, and audited tools.2MIT