A Model Context Protocol server for ArangoDB
This is a TypeScript-based MCP server that provides database interaction capabilities through ArangoDB. It implements core database operations and allows seamless integration with ArangoDB through MCP tools. You can use it wih Claude app and also extension for VSCode that works with mcp like Cline!
-
arango_query
- Execute AQL queries- Takes an AQL query string as 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 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
The server is database-structure agnostic and can work with any collection names or structures as long as they follow ArangoDB's document and edge collection models.
Install dependencies:
npm run build
For development with auto-rebuild:
npm run watch
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, add the server config:
- MacOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%/Claude/claude_desktop_config.json
To use with Cline VSCode Extension, add the server config:
- 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_DATABASE": "your_database_name",
"ARANGO_USERNAME": "your_username",
"ARANGO_PASSWORD": "your_password"
}
}
}
}
The server requires the following environment variables:
ARANGO_URL
- ArangoDB server URL (note: 8529 is the default port for ArangoDB for local development)ARANGO_DATABASE
- Database nameARANGO_USERNAME
- Database userARANGO_PASSWORD
- Database password
You can pretty much provide any meaningful prompt and Claude will try to execute the appropriate function.
Some example propmts:
- "List all collections in the database"
- "Query all users"
- "Insert a new document with name 'John Doe' and email "[email protected]' 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'"
Query all users:
{
"query": "FOR user IN users RETURN user"
}
Insert a new document:
{
"collection": "users",
"document": {
"name": "John Doe",
"email": "[email protected]"
}
}
Update a document:
{
"collection": "users",
"key": "123456",
"update": {
"name": "Jane Doe"
}
}
Remove a document:
{
"collection": "users",
"key": "123456"
}
List all collections:
{} // No parameters required
Backup database collections:
{
"outputDir": "./backup" // Specify an absolute output directory path for the backup files (optional)
"collection": "users" // Specify a collection name to backup (optional) If no collection name is provided, all collections will be backed up
"docLimit": 1000 // Specify the maximum number of documents to backup per collection (optional), if not provided, all documents will be backed up (not having a limit might cause timeout for large collections)
}
Create a new collection:
{
"name": "products",
"type": 2, // 2 for document collection, 3 for edge collection (optional, defaults to document collection)
"waitForSync": false // Optional, defaults to false
}
Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector for development:
npm run inspector
The Inspector will provide a URL to access debugging tools in your browser.
This project is licensed under the MIT License - see the LICENSE file for details.