ppidadi21/arangodb-mcp-server repository overview

⁠ArangoDB MCP Server

An [MCP] server that lets AI assistants such as Cursor and Claude Desktop query ArangoDB: run AQL, read documents, and explore schemas.

Tools: execute-aql-query, read-documents-with-filter, fetch-schemas, get-aql-manual

⁠Quick start: local use (stdio)

The MCP client starts the container itself, so no network port is opened and no token is needed. Add this to your client config (e.g. ~/.cursor/mcp.json):

{
  "mcpServers": {
    "arangodb": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "ARANGO_HOSTS=https://your-arangodb:8529",
        "-e", "ARANGO_USERNAME=your_user",
        "-e", "ARANGO_PASSWORD=your_password",
        "-e", "ARANGO_DEFAULT_DB_NAME=your_db",
        "ppidadi21/arangodb-mcp-server:1.1.0-rc1"
      ]
    }
  }
}

To keep the password out of the config, put the variables in an env file and use "--env-file", "/path/to/arangodb.env" instead of the -e lines.

⁠Quick start: shared server (HTTP)

Run one server that several clients connect to by URL. Each client sends its own ArangoDB token, and queries run with that user's permissions.

docker run -d --name arangodb-mcp -p 8080:8080 \
  -e MCP_TRANSPORT=http \
  -e MCP_REQUIRE_AUTH=true \
  -e MCP_ALLOWED_HOSTS=mcp.example.com \
  -e ARANGO_HOSTS=https://your-arangodb:8529 \
  -e ARANGO_USERNAME=your_service_user \
  -e ARANGO_PASSWORD=your_password \
  -e ARANGO_DEFAULT_DB_NAME=your_db \
  ppidadi21/arangodb-mcp-server:1.1.0-rc1

Client config:

{
  "mcpServers": {
    "arangodb": {
      "url": "https://mcp.example.com/",
      "headers": { "Authorization": "Bearer <ArangoDB JWT>" }
    }
  }
}

Get a token with POST /_open/auth on your ArangoDB deployment ({"username": "...", "password": "..."}). Tokens expire after about an hour.

HTTP mode requires MCP_REQUIRE_AUTH=true when it listens on a network interface, which is always the case in Docker. For use without a token, choose the stdio setup above.

⁠Configuration

⁠Notes

• ArangoDB Platform: set ARANGO_AUTH_METHOD=jwt.
• HTTPS: the server speaks plain HTTP; put it behind a TLS-terminating proxy or gateway for remote access, and add the public host name to MCP_ALLOWED_HOSTS.
• Kubernetes with a read-only root filesystem: mount a writable emptyDir at /tmp.
• Health check: GET /health returns 200 when ArangoDB is reachable (HTTP mode).

⁠Tags

• 1.1.0-rc1: release candidate (stdio and streamable HTTP, JWT authentication, per-user tokens)