ArangoDB MCP Server for Python

You run a production-ready MCP server that exposes ArangoDB operations to AI assistants. It provides async-first Python tooling, rich graph management, content conversion, backup/restore, analytics, and production-grade reliability. Use it to drive complex ArangoDB workflows from conversational agents or automated workflows with safe, typed input validation.

How to use

Connect an MCP client to the ArangoDB MCP server to perform 43 MCP tools across data operations, graph management, analytics, and design-pattern workflows. Use the client to execute queries, manage collections and graphs, inspect query plans, validate documents, and advance or unload tools within contexts. You can operate via a local stdio server for desktop clients or via an HTTP transport when hosting a web-facing or containerized service.

How to install

Prerequisites: you need Python 3.11 or newer and Docker Desktop to run ArangoDB locally.

# Install the MCP server package from PyPI
pip install mcp-arangodb-async

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

# Verify the MCP server can start and report health
python -m mcp_arangodb_async --health

Configuration

Required environment variables to connect to ArangoDB and run the MCP server from the command line are set in the runtime environment when you start the server.

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

Usage patterns and tips

• Use the stdio transport for desktop clients by starting the MCP server as a local process and configuring your client with the provided command and environment variables.

• For containerized deployments or web hosting, expose the MCP server via HTTP transport when you have a URL and host setup. The HTTP transport is initialized with a Python command that runs the HTTP server and binds to a host/port.

Example workflows with a codebase graph

Model your codebase as a graph to analyze dependencies, detect circular references, and visualize architecture using the 43 MCP tools. Create a graph, import modules and functions, traverse edges to reveal dependencies, and export the structure as Markdown for diagrams.

Troubleshooting

Common issues include ArangoDB connection problems, server startup failures in the client, and tool execution errors. Ensure ArangoDB is running, verify credentials, and review logs for detailed errors. If the server cannot start in the client, confirm you are using Python 3.11+ and that the MCP module starts health checks correctly.

Notes and considerations

This server supports a broad set of operations through 43 MCP tools, including queries, collection and index management, graph operations, validation, bulk operations, traversal, backup/restore, and analytics. It is designed for production use with retry logic, graceful degradation, and typed parameter validation.

Examples and further reading

Explore usage examples and tool references to see concrete workflows and tool summaries. Use the tools to build and analyze graphs, validate documents, and profile queries.

Available tools

arango_query

Execute AQL queries against ArangoDB and return results to the MCP client.

arango_list_collections

List all collections in the target ArangoDB database.

arango_insert

Insert documents into a collection with optional validation.

arango_update

Update documents in a collection using a matching filter.

arango_remove

Remove documents from a collection by filter or ID.

arango_create_collection

Create a new collection in the database.

arango_backup

Back up specified collections for recovery or export.

arango_list_indexes

List indexes on a collection.

arango_create_index

Create a new index on a collection.

arango_delete_index

Delete an index from a collection.

arango_explain_query

Explain the execution plan of an AQL query.

arango_query_builder

Build AQL queries programmatically.

arango_query_profile

Profile and optimize query performance.

arango_validate_references

Validate document references across collections.

arango_insert_with_validation

Insert documents with schema validation.

arango_create_schema

Create JSON schemas for data validation.

arango_validate_document

Validate a document against a schema.

arango_bulk_insert

Insert multiple documents efficiently.

arango_bulk_update

Update multiple documents in bulk.

arango_create_graph

Create named graphs and graph structures.

arango_list_graphs

List all graphs defined in the database.

arango_add_vertex_collection

Add vertex collections to a graph.

arango_add_edge_definition

Add edge definitions to a graph.

arango_add_vertex

Add vertices to a graph.

arango_add_edge

Add edges between vertices to form relationships.

arango_graph_traversal

Traverse a graph to discover connected elements.

arango_traverse

Alias for graph traversal to navigate graph structures.

arango_shortest_path

Find the shortest path between two vertices in a graph.

arango_backup_graph

Backup a single graph for safe restore.

arango_restore_graph

Restore a single graph from a backup.

arango_backup_named_graphs

Backup all named graphs in the database.

arango_validate_graph_integrity

Check graph integrity and consistency.

arango_graph_statistics

Provide statistics about graphs and collections.

arango_database_status

Return overall status of the ArangoDB database.

arango_search_tools

Search available MCP tools by keywords.

arango_list_tools_by_category

List tools grouped by category.

arango_switch_context

Switch the active workflow context.

arango_get_active_context

Retrieve the current active context.

arango_list_contexts

List all defined contexts.

arango_advance_workflow_stage

Advance the current workflow stage in a context.

arango_get_tool_usage_stats

Get usage statistics for tools.

arango_unload_tools

Unload specific tools from the MCP server.

arango_graph_traversal

Alias for arango_traverse