📌Overview

Purpose: The MCP Server for ArangoDB aims to facilitate seamless database interaction through a TypeScript-based server, leveraging the Model Context Protocol (MCP) for efficient communication.

Overview: This framework provides a robust interface for interacting with ArangoDB, enabling users to perform essential database operations. It is designed to integrate smoothly with tools like Claude app and the Cline extension for VSCode, enhancing database management capabilities.

Key Features:

arango_query: Execute AQL queries, optionally with bind variables, returning results in JSON format.
arango_insert: Insert documents into collections, generating document keys automatically if needed, while returning document metadata.
arango_update: Update existing documents by specifying the collection name, document key, and update object, followed by returning the updated document metadata.
arango_remove: Remove documents from specified collections, returning metadata of the deleted document.
arango_backup: Backup all collections into JSON files for data preservation and migration, specifying an output directory.
arango_list_collections: Retrieve a list of all collections in the database, including metadata like names and IDs.
arango_create_collection: Create new collections with configuration options for type and sync behavior, returning relevant collection information.

MCP Server for ArangoDB

A Model Context Protocol server for ArangoDB

This TypeScript-based MCP server provides database interaction capabilities through ArangoDB. It implements core database operations and allows seamless integration with ArangoDB through MCP tools. You can use it with the Claude app and also with the VSCode extension that works with MCP such as Cline.

Features

Tools

arango_query - Execute AQL queries
- Takes an AQL query string as a required parameter
- Optionally accepts bind variables for parameterized queries
- Returns query results as JSON
arango_insert - Insert documents into collections
- Takes collection name and document object as required parameters
- Automatically generates document key if not provided
- Returns the created document metadata
arango_update - Update existing documents
- Takes collection name, document key, and update object as required parameters
- Returns the updated document metadata
arango_remove - Remove documents from collections
- Takes collection name and document key as required parameters
- Returns the removed document metadata
arango_backup - Backup all collections to JSON files
- Takes output directory path as required parameter
- Creates JSON files for each collection with current data
- Useful for data backup and migration purposes
arango_list_collections - List all collections in the database
- Returns an array of collection information including names, IDs, and types
arango_create_collection - Create a new collection in the database
- Takes collection name as required parameter
- Optionally specify collection type (document or edge collection)
- Configure waitForSync behavior for write operations
- Returns collection information including name, type, and status

Installation

Installing via NPM

To install arango-server globally via NPM, run:

npm install -g arango-server

Running via NPX

To run arango-server directly without installation, use:

npx arango-server

Configuring for VSCode Agent

To use arango-server with the VSCode Copilot agent, you must have at least VSCode 1.99.0 installed and follow these steps:

Create or edit the MCP configuration file:
- Workspace-specific configuration: Create or edit the .vscode/mcp.json file in your workspace.
- User-specific configuration: Optionally, specify the server in the MCP VS Code user settings to enable the MCP server across all workspaces.

Add the following configuration:

{
    "servers": {
        "arango-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": ["arango-server"],
            "env": {
                "ARANGO_URL": "http://localhost:8529",
                "ARANGO_DB": "v20",
                "ARANGO_USERNAME": "app",
                "ARANGO_PASSWORD": "75Sab@MYa3Dj8Fc"
            }
        }
    }
}

Start the MCP server:
- Open the Command Palette in VSCode (Ctrl+Shift+P or Cmd+Shift+P on Mac).
- Run the command MCP: Start Server and select arango-mcp from the list.
Verify the server:
- Open the Chat view in VSCode and switch to Agent mode.
- Use the Tools button to verify that the arango-server tools are available.

Installing via Smithery

To install ArangoDB for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @ravenwits/mcp-server-arangodb --client claude

To use with Claude Desktop

Go to: Settings > Developer > Edit Config or use the configuration file at:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

To use with Cline VSCode Extension

Go to: Cline Extension > MCP Servers > Edit Configuration or use the configuration file at:

MacOS: ~/Library/Application Support/Code/User/globalStorage/cline.cline/config.json
Windows: %APPDATA%/Code/User/globalStorage/cline.cline/config.json

Add the following configuration to the mcpServers section:

{
  "mcpServers": {
    "arango": {
      "command": "node",
      "args": ["/path/to/arango-server/build/index.js"],
      "env": {
        "ARANGO_URL": "your_database_url",
        "ARANGO_DB": "your_database_name",
        "ARANGO_USERNAME": "your_username",
        "ARANGO_PASSWORD": "your_password"
      }
    }
  }
}

Environment Variables

The server requires the following environment variables:

ARANGO_URL - ArangoDB server URL (default port: 8529)
ARANGO_DB - Database name
ARANGO_USERNAME - Database username
ARANGO_PASSWORD - Database password

Usage

You can provide any meaningful prompt and Claude will try to execute the appropriate function.

Example prompts:

"List all collections in the database"
"Query all users"
"Insert a new document with name 'John Doe' and email 'john@example.com' to the 'users' collection"
"Update the document with key '123456' or name 'Jane Doe' to change the age to 48"
"Create a new collection named 'products'"

Example Commands

Query all users:

{
  "query": "FOR user IN users RETURN user"
}

Insert a new document:

{
  "collection": "users",
  "document": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Update a document:

{
  "collection": "users",
  "key": "123456",
  "update": {
    "name": "Jane Doe"
  }
}

Remove a document:

{
  "collection": "users",
  "key": "123456"
}

List all collections:

{}

Backup database collections:

{
  "outputDir": "./backup",        // Optional: output directory path for backup files  
  "collection": "users",          // Optional: specify collection name to backup  
  "docLimit": 1000                // Optional: max documents to backup per collection  
}

Create a new collection:

{
  "name": "products",
  "type": 2,            // 2 for document collection, 3 for edge collection (optional, default: document collection)
  "waitForSync": false  // Optional, default: false
}

Note: The server is database-structure agnostic and works with any collection names or structures that follow ArangoDB's document and edge collection models.

Development

Clone the repository
Install dependencies and build:
```
npm run build
```
For development with auto-rebuild:
```
npm run watch
```

Debugging

MCP servers communicate over stdio, so debugging can be challenging. It is recommended to use MCP Inspector for development:

npm run inspector

The Inspector provides a URL to access debugging tools in your browser.

License

This project is licensed under the MIT License. See the LICENSE file for details.