arangodb/mcp-arangodb repository overview

⁠Quick reference

• Maintained by: ArangoDB
• Where to get help: GitHub Issues⁠

⁠Supported tags

⁠latest, 1.0.0

⁠Supported architectures

⁠linux/amd64, linux/arm64

⁠What is mcp-arangodb?

This Docker image provides a Model Context Protocol (MCP) server that enables AI assistants to interact with ArangoDB. It exposes ArangoDB’s database features to tools such as Cursor or Claude MCP-enabled environments, enabling automated and AI-assisted database workflows.

⁠Capabilities

• Executing AQL queries
• Exploring collections, graphs, and indexes
• Retrieving structured results into LLM prompts
• AI-assisted workflows on ArangoDB data

⁠Key Features

• Built-in AQL manuals and optimization guides
• Schema discovery from existing database collections
• AQL generation and execution with bind variable support
• Docker-based deployment for consistent environments
• Secure environment-variable configuration

⁠Available MCP Tools

⁠Prerequisites

Before using this image, ensure you have:

• Docker installed and running
• ArangoDB instance (version 3.11+)
• Cursor IDE or other MCP-compatible client

⁠How to use this image

⁠1. Start ArangoDB (example below)

docker run -d --name arangodb \
  -p 8529:8529 \
  -e ARANGO_ROOT_PASSWORD=test \
  arangodb:latest

⁠2. Pull the MCP image

docker pull arangodb/mcp-arangodb:latest

⁠3. Run the MCP container (Optional - for testing)

docker run -i --rm --network host \
  -e ARANGO_HOSTS=http://localhost:8529 \
  -e ARANGO_ROOT_USERNAME=root \
  -e ARANGO_ROOT_PASSWORD=test \
  -e ARANGO_DEFAULT_DB_NAME=_system \
  arangodb/mcp-arangodb:latest

If the container starts successfully and shows no errors, stop the container and proceed to configure Cursor.

⁠4. Configure Cursor

Add to your workspace's .cursor/mcp.json or global ~/.cursor/mcp.json:

{
  "mcpServers": {
    "arangodb-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network", "host",
        "-e", "ARANGO_HOSTS=http://localhost:8529",
        "-e", "ARANGO_ROOT_USERNAME=root",
        "-e", "ARANGO_ROOT_PASSWORD=test",
        "-e", "ARANGO_DEFAULT_DB_NAME=_system",
        "arangodb/mcp-arangodb:latest"
      ]
    }
  }
}

⁠5. Restart Cursor

After restarting Cursor, the MCP server should automatically connect.

⁠6. Verify Connection

To verify the MCP server is working:

1. Check the MCP status indicator in Cursor's "Tools & MCP" view
2. You should see "arangodb-mcp" listed as connected
3. Test with a simple query: "List 5 documents in the users collection"

⁠Environment Variables

The MCP server supports both HTTP and HTTPS connections to ArangoDB with flexible SSL/TLS certificate verification options.

⁠HTTPS with Certificate Verification (Production)

For production environments with SSL-enabled ArangoDB, mount your certificate file into the container and configure verification:

docker run -i --rm --network host \
  -v /path/to/certs:/certs:ro \
  -e ARANGO_HOSTS=https://localhost:8530 \
  -e ARANGO_ROOT_USERNAME=root \
  -e ARANGO_ROOT_PASSWORD=your_password \
  -e ARANGO_DEFAULT_DB_NAME=production_db \
  -e ARANGO_VERIFY_SSL=true \
  -e ARANGO_SSL_CERT_PATH=/certs/arango-ca.pem \
  arangodb/mcp-arangodb:latest

Cursor Configuration with SSL Verification:

{
  "mcpServers": {
    "arangodb-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network", "host",
        "-v", "/path/to/certs:/certs:ro",
        "-e", "ARANGO_HOSTS=https://localhost:8530",
        "-e", "ARANGO_ROOT_USERNAME=root",
        "-e", "ARANGO_ROOT_PASSWORD=your_password",
        "-e", "ARANGO_DEFAULT_DB_NAME=production_db",
        "-e", "ARANGO_VERIFY_SSL=true",
        "-e", "ARANGO_SSL_CERT_PATH=/certs/arango-ca.pem",
        "arangodb/mcp-arangodb:latest"
      ]
    }
  }
}

⁠HTTPS without Verification (Development/Testing)

For testing with self-signed certificates where verification is not needed:

docker run -i --rm --network host \
  -e ARANGO_HOSTS=https://localhost:8530 \
  -e ARANGO_ROOT_USERNAME=root \
  -e ARANGO_ROOT_PASSWORD=dev_password \
  -e ARANGO_DEFAULT_DB_NAME=test_db \
  -e ARANGO_VERIFY_SSL=false \
  arangodb/mcp-arangodb:latest

Warning: This disables certificate verification and should only be used in development/testing environments. Never use this in production!

⁠Cluster Configuration with SSL

For ArangoDB clusters with multiple coordinators over HTTPS:

docker run -i --rm \
  -v /path/to/certs:/certs:ro \
  -e ARANGO_HOSTS=https://coordinator1:8529,https://coordinator2:8529,https://coordinator3:8529 \
  -e ARANGO_ROOT_USERNAME=root \
  -e ARANGO_ROOT_PASSWORD=your_password \
  -e ARANGO_DEFAULT_DB_NAME=production_db \
  -e ARANGO_VERIFY_SSL=true \
  -e ARANGO_SSL_CERT_PATH=/certs/cluster-ca.pem \
  arangodb/mcp-arangodb:latest

⁠Debugging

If Cursor displays:

No tools, prompts, or custom resources

the MCP server likely failed to start.

⁠Check the docker logs for further debugging information

docker logs <container-name>

⁠Confirm ArangoDB is running

docker ps | grep arangodb
curl http://localhost:8529/_api/version

⁠Common issues

• Incorrect ARANGO_ROOT_PASSWORD
• ArangoDB container not running
• Docker network connectivity issues
• Missing environment variables

⁠License

Users must ensure compliance with all applicable licenses.

• MCP server: MIT License
• Other dependencies under respective licenses

⁠Summary