{
  "markdown": "<!-- mcp-name: io.github.PCfVW/mcp-arangodb-async -->\n\n# ArangoDB MCP Server for Python\n\n[![Python](https://img.shields.io/badge/Python-3.11%2B-blue)](https://www.python.org/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-green.svg)](https://github.com/PCfVW/mcp-arango-async/blob/master/LICENSE)\n[![MCP](https://img.shields.io/badge/Protocol-MCP-%23555555)](https://modelcontextprotocol.io/)\n[![PyPI](https://img.shields.io/pypi/v/mcp-arangodb-async)](https://pypi.org/project/mcp-arangodb-async/)\n\nA production-ready Model Context Protocol (MCP) server exposing advanced ArangoDB operations to AI assistants like Claude Desktop and Augment Code. Features async-first Python architecture, comprehensive graph management, flexible content conversion (JSON, Markdown, YAML, Table), backup/restore functionality, and analytics capabilities.\n\n---\n\n## Quick Links\n\n📚 **Documentation:** [https://github.com/PCfVW/mcp-arango-async/tree/master/docs](https://github.com/PCfVW/mcp-arango-async/tree/master/docs)\n\n🚀 **Quick Start:** [https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/quickstart.md](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/quickstart.md)\n\n🔧 **ArangoDB Setup:** [https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/install-arangodb.md](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/install-arangodb.md)\n\n🗄️ **Multi-Tenancy Guide:** [https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/multi-tenancy-guide.md](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/multi-tenancy-guide.md)\n\n⚙️ **CLI Reference:** [https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/cli-reference.md](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/cli-reference.md)\n\n📖 **Tools Reference:** [https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/tools-reference.md](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/tools-reference.md)\n\n🎯 **MCP Design Patterns:** [https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/mcp-design-patterns.md](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/mcp-design-patterns.md)\n\n📝 **Changelog:** [https://github.com/PCfVW/mcp-arango-async/blob/master/docs/developer-guide/changelog.md](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/developer-guide/changelog.md)\n\n🐛 **Issues:** [https://github.com/PCfVW/mcp-arango-async/issues](https://github.com/PCfVW/mcp-arango-async/issues)\n\n---\n\n## Features\n\n- ✅ **46 MCP Tools** - Complete ArangoDB operations (queries, collections, indexes, graphs)\n- ✅ **Multi-Tenancy** - Work with multiple databases, environment switching, cross-database operations\n- ✅ **MCP Design Patterns** - Progressive discovery, context switching, tool unloading (98.7% token savings)\n- ✅ **Graph Management** - Create, traverse, backup/restore named graphs\n- ✅ **Content Conversion** - JSON, Markdown, YAML, and Table formats\n- ✅ **Backup/Restore** - Collection and graph-level backup with validation\n- ✅ **Analytics** - Query profiling, explain plans, graph statistics\n- ✅ **Dual Transport** - stdio (desktop clients) and HTTP (web/containerized)\n- ✅ **Docker Support** - Run in Docker for isolation and reproducibility\n- ✅ **Production-Ready** - Retry logic, graceful degradation, comprehensive error handling\n- ✅ **Type-Safe** - Pydantic validation for all tool arguments\n\n---\n\n## Architecture\n\n```\n┌────────────────────┐      ┌─────────────────────┐       ┌──────────────────┐\n│   MCP Client       │      │  ArangoDB MCP       │       │   ArangoDB       │\n│ (Claude, Augment)  │─────▶│  Server (Python)    │─────▶│  (Docker)        │\n│                    │      │  • 46 Tools         │       │  • Multi-Model   │\n│                    │      │  • Multi-Tenancy    │       │  • Graph Engine  │\n│                    │      │  • Graph Mgmt       │       │  • AQL Engine    │\n│                    │      │  • MCP Patterns     │       │                  │\n└────────────────────┘      └─────────────────────┘       └──────────────────┘\n```\n\n---\n\n## Getting Started with ArangoDB\n\n### Prerequisites\n\n- **Docker and Docker Compose** installed\n- **Python 3.11+** (for mcp-arangodb-async)\n\n### Step 1: Install ArangoDB\n\nCreate a `docker-compose.yml` file:\n\n```yaml\nservices:\n  arangodb:\n    image: arangodb:3.11\n    environment:\n      ARANGO_ROOT_PASSWORD: ${ARANGO_ROOT_PASSWORD:-changeme}\n    ports:\n      - \"8529:8529\"\n    volumes:\n      - arangodb_data:/var/lib/arangodb3\n      - arangodb_apps:/var/lib/arangodb3-apps\n    healthcheck:\n      test: arangosh --server.username root --server.password \"$ARANGO_ROOT_PASSWORD\" --javascript.execute-string \"require('@arangodb').db._version()\" > /dev/null 2>&1 || exit 1\n      interval: 5s\n      timeout: 2s\n      retries: 30\n    restart: unless-stopped\n\nvolumes:\n  arangodb_data:\n    driver: local\n  arangodb_apps:\n    driver: local\n```\n\nCreate a `.env` file:\n\n```bash\n# ArangoDB root password\nARANGO_ROOT_PASSWORD=changeme\n\n# MCP Server connection settings\nARANGO_URL=http://localhost:8529\nARANGO_DB=mcp_arangodb_test\nARANGO_USERNAME=mcp_arangodb_user\nARANGO_PASSWORD=mcp_arangodb_password\n```\n\nStart ArangoDB:\n\n```bash\ndocker compose --env-file .env up -d\n```\n\n### Step 2: Install mcp-arangodb-async\n\nInstall the MCP server package:\n\n```bash\npip install mcp-arangodb-async\n```\n\n<details>\n<summary><b>Alternative: Install with Conda/Mamba/Micromamba</b></summary>\n\n```bash\n# Create environment and install\nconda create -n mcp-arango python=3.11\nconda activate mcp-arango\npip install mcp-arangodb-async\n\n# Or with mamba/micromamba:\n# mamba create -n mcp-arango python=3.11\n# mamba activate mcp-arango\n# pip install mcp-arangodb-async\n```\n\n</details>\n\n<details>\n<summary><b>Alternative: Install with uv</b></summary>\n\n```bash\n# Create environment and install\nuv venv .venv --python 3.11\nuv pip install mcp-arangodb-async\n```\n\n</details>\n\n### Step 3: Create Database and User\n\nCreate the database and user for the MCP server:\n\n```bash\nmaa db add mcp_arangodb_test \\\n  --url http://localhost:8529 \\\n  --with-user mcp_arangodb_user \\\n  --env-file .env\n```\n\n**Expected output:**\n```\nThe following actions will be performed:\n  [ADD] Database 'mcp_arangodb_test'\n  [ADD] User 'mcp_arangodb_user' (active: true)\n  [GRANT] Permission rw: mcp_arangodb_user → mcp_arangodb_test\n\nAre you sure you want to proceed? [y/N]: y\ndb add:\n[ADDED] Database 'mcp_arangodb_test'\n[ADDED] User 'mcp_arangodb_user' (active: true)\n[GRANTED] Permission rw: mcp_arangodb_user → mcp_arangodb_test\n```\n\nVerify the database connection:\n\n```bash\n# Set environment variables\nexport ARANGO_URL=http://localhost:8529\nexport ARANGO_DB=mcp_arangodb_test\nexport ARANGO_USERNAME=mcp_arangodb_user\nexport ARANGO_PASSWORD=mcp_arangodb_password\n\n# Run health check\nmaa health\n```\n\n**Expected output:**\n```json\n{\"status\": \"healthy\", \"database_connected\": true, \"database_info\": {\"version\": \"3.11.x\", \"name\": \"mcp_arangodb_test\"}}\n```\n\n### Step 4: Configure MCP Host\n\nConfigure your MCP host to use the server. The configuration includes environment variables for database connection. The location of the configuration file depends on your MCP host. For Claude Desktop, the file is located at:\n\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Linux:** `~/.config/Claude/claude_desktop_config.json`\n\n**Configuration:**\n\n```json\n{\n  \"mcpServers\": {\n    \"arangodb\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcp_arangodb_async\"],\n      \"env\": {\n        \"ARANGO_URL\": \"http://localhost:8529\",\n        \"ARANGO_DB\": \"mcp_arangodb_test\",\n        \"ARANGO_USERNAME\": \"mcp_arangodb_user\",\n        \"ARANGO_PASSWORD\": \"mcp_arangodb_password\"\n      }\n    }\n  }\n}\n```\n\n<details>\n<summary><b>Alternative: Configuration for Conda/Mamba/Micromamba</b></summary>\n\nIf you installed with conda/mamba/micromamba, use the `run` command:\n\n```json\n{\n  \"mcpServers\": {\n    \"arangodb\": {\n      \"command\": \"conda\",\n      \"args\": [\"run\", \"-n\", \"mcp-arango\", \"maa\", \"server\"],\n      \"env\": {\n        \"ARANGO_URL\": \"http://localhost:8529\",\n        \"ARANGO_DB\": \"mcp_arangodb_test\",\n        \"ARANGO_USERNAME\": \"mcp_arangodb_user\",\n        \"ARANGO_PASSWORD\": \"mcp_arangodb_password\"\n      }\n    }\n  }\n}\n```\n\nReplace `\"conda\"` with `\"mamba\"` or `\"micromamba\"` if using those tools.\n\n</details>\n\n<details>\n<summary><b>Alternative: Configuration for uv</b></summary>\n\nIf you installed with uv, use `uv run`:\n\n```json\n{\n  \"mcpServers\": {\n    \"arangodb\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/project\", \"maa\", \"server\"],\n      \"env\": {\n        \"ARANGO_URL\": \"http://localhost:8529\",\n        \"ARANGO_DB\": \"mcp_arangodb_test\",\n        \"ARANGO_USERNAME\": \"mcp_arangodb_user\",\n        \"ARANGO_PASSWORD\": \"mcp_arangodb_password\"\n      }\n    }\n  }\n}\n```\n\nReplace `/path/to/project` with the directory containing your `.venv` folder.\n\n</details>\n\n**Restart your MCP client** after updating the configuration.\n\n**Test the connection:**\n\nAsk your MCP client: *\"List all collections in the ArangoDB database\"*\n\nThe assistant should successfully connect and list your collections.\n\n## Available Tools\n\nThe server exposes **46 MCP tools** organized into 11 categories:\n\n### Multi-Tenancy Tools (4 tools)\n- `arango_set_focused_database` - Set focused database for session\n- `arango_get_focused_database` - Get currently focused database\n- `arango_list_available_databases` - List all configured databases\n- `arango_get_database_resolution` - Show database resolution algorithm\n\n### Core Data Operations (7 tools)\n- `arango_query` - Execute AQL queries\n- `arango_list_collections` - List all collections\n- `arango_insert` - Insert documents\n- `arango_update` - Update documents\n- `arango_remove` - Remove documents\n- `arango_create_collection` - Create collections\n- `arango_backup` - Backup collections\n\n### Index Management (3 tools)\n- `arango_list_indexes` - List indexes\n- `arango_create_index` - Create indexes\n- `arango_delete_index` - Delete indexes\n\n### Query Analysis (3 tools)\n- `arango_explain_query` - Explain query execution plan\n- `arango_query_builder` - Build AQL queries\n- `arango_query_profile` - Profile query performance\n\n### Data Validation (4 tools)\n- `arango_validate_references` - Validate document references\n- `arango_insert_with_validation` - Insert with validation\n- `arango_create_schema` - Create JSON schemas\n- `arango_validate_document` - Validate against schema\n\n### Bulk Operations (2 tools)\n- `arango_bulk_insert` - Bulk insert documents\n- `arango_bulk_update` - Bulk update documents\n\n### Graph Management (7 tools)\n- `arango_create_graph` - Create named graphs\n- `arango_list_graphs` - List all graphs\n- `arango_add_vertex_collection` - Add vertex collections\n- `arango_add_edge_definition` - Add edge definitions\n- `arango_add_vertex` - Add vertices\n- `arango_add_edge` - Add edges\n- `arango_graph_traversal` - Traverse graphs\n\n### Graph Traversal (2 tools)\n- `arango_traverse` - Graph traversal\n- `arango_shortest_path` - Find shortest paths\n\n### Graph Backup/Restore (5 tools)\n- `arango_backup_graph` - Backup single graph\n- `arango_restore_graph` - Restore single graph\n- `arango_backup_named_graphs` - Backup all named graphs\n- `arango_validate_graph_integrity` - Validate graph integrity\n- `arango_graph_statistics` - Graph statistics\n\n### Health & Status (1 tool)\n- `arango_database_status` - Get comprehensive status of all databases\n\n### Tool Aliases (2 tools)\n- `arango_graph_traversal` - Alias for arango_traverse\n- `arango_add_vertex` - Alias for arango_insert\n\n### MCP Design Pattern Tools (8 tools)\n- `arango_search_tools` - Search for tools by keywords\n- `arango_list_tools_by_category` - List tools by category\n- `arango_switch_workflow` - Switch workflow context\n- `arango_get_active_workflow` - Get active workflow\n- `arango_list_workflows` - List all workflows\n- `arango_advance_workflow_stage` - Advance workflow stage\n- `arango_get_tool_usage_stats` - Get tool usage statistics\n- `arango_unload_tools` - Unload specific tools\n\n📖 **Complete tools reference:** [https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/tools-reference.md](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/tools-reference.md)\n\n📖 **MCP Design Patterns Guide:** [https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/mcp-design-patterns.md](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/mcp-design-patterns.md)\n\n---\n\n## Use Case Example: Codebase Graph Analysis\n\nModel your codebase as a graph to analyze dependencies, find circular references, and understand architecture. Here is an excerpt from the longer [codebase analysis example](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/examples/codebase-analysis.md):\n\n```python\n# 1. Create graph structure\nAsk Claude: \"Create a graph called 'codebase' with vertex collections 'modules' and 'functions', and edge collection 'calls' connecting functions\"\n\n# 2. Import codebase data\nAsk Claude: \"Insert these modules into the 'modules' collection: [...]\"\n\n# 3. Analyze dependencies\nAsk Claude: \"Find all functions that depend on the 'auth' module using graph traversal\"\n\n# 4. Detect circular dependencies\nAsk Claude: \"Check for circular dependencies in the codebase graph\"\n\n# 5. Generate architecture diagram\nAsk Claude: \"Export the codebase graph structure as Markdown for visualization\"\n```\n\n📖 [More examples](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/examples/codebase-analysis.md)\n\n---\n\n## Documentation\n\n### Getting Started\n- [ArangoDB Installation](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/install-arangodb.md)\n- [Quickstart Guide](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/quickstart.md)\n- [Install from Source](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/install-from-source.md)\n- [First Interaction](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/first-interaction.md)\n\n### Configuration\n- [Transport Configuration](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/configuration/transport-configuration.md)\n- [Environment Variables](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/configuration/environment-variables.md)\n\n### User Guide\n- [Tools Reference](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/tools-reference.md)\n- [Troubleshooting](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/troubleshooting.md)\n\n### Developer Guide\n- [Architecture Overview](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/developer-guide/architecture.md)\n- [Low-Level MCP Rationale](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/developer-guide/low-level-mcp-rationale.md)\n- [HTTP Transport](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/developer-guide/http-transport.md)\n- [Changelog](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/developer-guide/changelog.md)\n\n### Examples\n- [Codebase Dependency Analysis](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/examples/codebase-analysis.md)\n\n📖 **Full documentation:** [https://github.com/PCfVW/mcp-arango-async/tree/master/docs](https://github.com/PCfVW/mcp-arango-async/tree/master/docs)\n\n---\n\n## Troubleshooting\n\n### Common Issues\n\n**Database connection fails:**\n```bash\n# Check ArangoDB is running\ndocker ps | grep arangodb\n\n# Test connection\ncurl http://localhost:8529/_api/version\n\n# Check credentials\nmaa health\n```\n\n**Server won't start in Claude Desktop:**\n```bash\n# Verify Python installation\npython --version  # Must be 3.11+\n\n# Test module directly\nmaa health\n\n# Check Claude Desktop logs\n# Windows: %APPDATA%\\Claude\\logs\\\n# macOS: ~/Library/Logs/Claude/\n```\n\n**Tool execution errors:**\n- Verify ArangoDB is healthy: `docker compose ps`\n- Check environment variables are set correctly\n- Review server logs for detailed error messages\n\n📖 [Complete troubleshooting guide](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/troubleshooting.md)\n\n---\n\n## Why Docker for ArangoDB?\n\n✅ **Stability** - Isolated environment, no host conflicts  \n✅ **Zero-install** - Start/stop with `docker compose`  \n✅ **Reproducibility** - Same image across all environments  \n✅ **Health checks** - Built-in readiness validation  \n✅ **Fast reset** - Recreate clean instances easily  \n✅ **Portability** - Consistent on Windows/macOS/Linux\n\n---\n\n## License\n\n- **This project:** Apache License 2.0\n- **ArangoDB 3.11:** Apache License 2.0\n- **ArangoDB 3.12+:** Business Source License 1.1 (BUSL-1.1)\n\n⚠️ **Important:** This repository does not grant rights to ArangoDB binaries. You must comply with ArangoDB's license for your deployment version.\n\n📖 [License details](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/install-arangodb.md#licensing-considerations)\n\n---\n\n## Contributing\n\nContributions are welcome! Please see our documentation for guidelines.\n\n📖 [Architecture decisions](https://github.com/PCfVW/mcp-arango-async/blob/master/docs/developer-guide/low-level-mcp-rationale.md)\n\n---\n\n## Support\n\n- [Issues](https://github.com/PCfVW/mcp-arango-async/issues)\n- [Discussions](https://github.com/PCfVW/mcp-arango-async/discussions)\n- [Documentation](https://github.com/PCfVW/mcp-arango-async/tree/master/docs)\n\n---\n\n## Acknowledgments\n\nBuilt with:\n- [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic\n- [python-arango](https://github.com/ArangoDB-Community/python-arango) - Official ArangoDB Python driver\n- [Pydantic](https://docs.pydantic.dev/) - Data validation\n- [Starlette](https://www.starlette.io/) - HTTP transport\n- [ArangoDB](https://www.arangodb.com/) - Multi-model database\n\n",
  "bytes": 17948,
  "sha": "e9776d850ee329f11385cb1936ea8f63ab4273553a4eba58ec16f35b68665e26",
  "repo_slug": "pcfvw/mcp-arangodb-async",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pcfvw_mcp_arangodb_async_1a11bc8b/readme"
}