MCP ArangoDB

A Model Context Protocol (MCP) server for ArangoDB, providing full database access through MCP's standardized tool interface.

Features

• Collections: Create, list, and manage document and edge collections
• Documents: Full CRUD operations on documents
• Queries: Simple query tools and raw AQL execution
• Graphs: Graph creation, traversal, and edge management
• Two Transport Modes: StdIO (for AI tool integration) and HTTP/SSE (for web-based access)
• TypeScript: Full type safety with ArangoJS
• 95%+ Test Coverage: Unit, integration, and E2E tests

Architecture

┌─────────────────────────────────────────────────────────┐
│                      AI Tool                             │
│  (OpenClaw, Claude Desktop, etc.)                       │
└─────────────────────────┬───────────────────────────────┘
                          │ MCP Protocol
                          ▼
┌─────────────────────────────────────────────────────────┐
│                   MCP Server                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
│  │ Collections │  │  Documents  │  │     Queries     │  │
│  └─────────────┘  └─────────────┘  └─────────────────┘  │
│  ┌─────────────┐  ┌─────────────┐                       │
│  │   Graphs    │  │    AQL      │                       │
│  └─────────────┘  └─────────────┘                       │
└─────────────────────────┬───────────────────────────────┘
                          │ ArangoJS
                          ▼
┌─────────────────────────────────────────────────────────┐
│                      ArangoDB                            │
│            (Document + Graph Database)                    │
└─────────────────────────────────────────────────────────┘

Quick Start

1. Clone and Install

git clone https://github.com/TylerGarlick/mcp-arangodb.git
cd mcp-arangodb
bun install

2. Start ArangoDB

docker compose up -d

3. Run the MCP Server

# StdIO mode (default, for AI tool integration)
bun run dev

# Or HTTP mode (for web-based access)
bun run dev:http

Available Tools

Collections

Tool	Description
list_collections	List all collections
create_collection	Create a new collection
get_collection	Get collection information
delete_collection	Delete a collection
get_collection_indexes	List indexes for a collection

Documents

Tool	Description
create_document	Create a document
get_document	Get a document by ID
update_document	Update a document (patch)
replace_document	Replace a document (put)
delete_document	Delete a document

Queries

Tool	Description
query_by_example	Find documents matching an example
query_by_range	Find documents within a range
count_documents	Count documents in collection
execute_aql	Execute raw AQL query
generate_aql	Generate AQL from natural language

Graphs

Tool	Description
create_graph	Create a named graph
list_graphs	List all graphs
get_graph	Get graph information
delete_graph	Delete a graph
traverse_graph	Execute graph traversal
create_edge_collection	Create an edge collection
create_edge	Create an edge document
get_edge	Get an edge by ID

Documentation

• Setup Guide - Installation and configuration
• Usage Guide - Running the server and connecting AI tools
• Novice Guide - Introduction to ArangoDB and MCP
• Intermediate Guide - AQL, edges, and graphs
• Advanced Guide - Performance tuning and optimization
• AQL Reference - AQL syntax and examples

Testing

# Run all tests
bun test

# Run unit tests
bun run test:unit

# Run integration tests (requires ArangoDB)
bun run test:integration

# Run E2E tests
bun run test:e2e

# Run with coverage
bun run test:coverage

Environment Variables

Variable	Description	Default
ARANGO_HOST	ArangoDB server URL	http://localhost:8529
ARANGO_PASSWORD	Root password	(empty)
PORT	HTTP server port	3000
HOST	HTTP server host	0.0.0.0
TRANSPORT	Transport type (stdio or http)	stdio

Connecting to AI Tools

OpenClaw

mcp:
  servers:
    arangodb:
      command: bun
      args:
        - run
        - /path/to/mcp-arangodb/src/index.ts
      env:
        ARANGO_HOST: http://localhost:8529
        ARANGO_PASSWORD: password

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "arangodb": {
      "command": "bun",
      "args": ["/path/to/mcp-arangodb/src/index.ts"],
      "env": {
        "ARANGO_HOST": "http://localhost:8529",
        "ARANGO_PASSWORD": "password"
      }
    }
  }
}

License

MIT © Tyler Garlick