ArangoDB TypeScript MCP Server for Database Operations

Overview

This TypeScript Model Context Protocol (MCP) server provides a small, focused bridge between language models / agents (Claude, VS Code MCP-enabled agents, Cline, etc.) and ArangoDB. It exposes common database operations (queries, inserts, updates, deletes, backups, collection management) as MCP tools so an LLM-driven assistant can perform safe, parameterized database work without embedding credentials or SQL/AQL in the model itself.

For developers building agent-enabled applications, the server removes repetitive glue code: you get typed, prepared operations backed by ArangoDB AQL, environment-driven configuration, and an easy way to wire the service into VS Code, Claude Desktop, or other MCP-capable clients. Use it locally with npx for quick experimentation or install globally for broader integration with editor tooling.

Source / repo: https://github.com/ravenwits/mcp-server-arangodb

Features

• Execute AQL queries with bind variables
• Insert documents with automatic key generation
• Update documents by key
• Remove documents by key
• List and create collections (document or edge)
• Export all collections to JSON files for backup/migration
• TypeScript implementation, ready to build and run with Node
• Designed for integration with Claude, VSCode MCP, and Cline

Installation / Configuration

Requirements:

• Node 16+ (or current LTS)
• Access to an ArangoDB instance (local or remote)

Install via npm (global):

npm install -g arango-server

Run with npx (no install):

npx arango-server

Clone and run from source:

git clone https://github.com/ravenwits/mcp-server-arangodb.git
cd mcp-server-arangodb
npm install
npm run build
node build/index.js

Environment variables (required):

export ARANGO_URL="http://localhost:8529"
export ARANGO_DB="your_database_name"
export ARANGO_USERNAME="your_username"
export ARANGO_PASSWORD="your_password"

VS Code MCP configuration (workspace .vscode/mcp.json):

{
  "servers": {
    "arango-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["arango-server"],
      "env": {
        "ARANGO_URL": "http://localhost:8529",
        "ARANGO_DB": "my_db",
        "ARANGO_USERNAME": "root",
        "ARANGO_PASSWORD": "secret"
      }
    }
  }
}

Cline / other MCP clients: add an MCP server entry that runs the built index.js and injects the same ARANGO_* env vars.

Claude Desktop: add the server entry to claude_desktop_config.json under Developer / Edit Config, following the MCP docs.

Available Tools

The server exposes these tools to MCP clients. Table summarizes parameters and return values.

Example arango_query payload (how an MCP tool call looks conceptually):

{
  "tool": "arango_query",
  "params": {
    "query": "FOR u IN users FILTER u.age > @minAge RETURN u",
    "bindVars": { "minAge": 21 }
  }
}

The server validates parameters and returns structured JSON results so calling agents can reason about them or render them in an editor/chat UI.

Use Cases

• Ad-hoc data exploration from an LLM: ask an agent “List all collections” or “Show users with role = ‘admin’”; the agent invokes arango_list_collections or arango_query and presents results.
• CRUD support inside editor extensions: a VS Code agent can insert or update documents in response to a developer prompt or code action, using arango_insert / arango_update.
• Backups and migrations: schedule arango_backup to export each collection to JSON files for audits or migrations.
• Prototyping data-backed LLM workflows: wire Claude to the server to let the assistant perform parameterized queries, avoiding exposing DB credentials in prompts.

Concrete examples

• List collections (prompt → tool):
  • Prompt: “List all collections”
  • Action: arango_list_collections
• Insert a user:
  • Prompt: “Create user John Doe email [email protected] in users collection”
  • Tool call:

    {
      "tool": "arango_insert",
      "params": {
        "collection": "users",
        "document": { "name": "John Doe", "email": "[email protected]" }
      }
    }
    

• Backup DB:
  • Run: arango_backup with outDir “./backups/2026-04-10”

Notes for Developers

• The server expects safe, parameterized AQL when using arango_query; prefer bind variables to avoid injection risks.
• Use environment variables to avoid embedding secrets in config files.
• The TypeScript source is lightweight—extend tools or add new operations by following the existing tool pattern in the repo.
• Check the repository README and MCP documentation (https://modelcontextprotocol.io/docs) for details about MCP tool registration and capabilities.