🚀 Appwrite MCP Server

Transform Claude into your intelligent Appwrite management assistant
16 optimized tools • Core Appwrite operations • Context-efficient design • Production-ready

---

A context-optimized Model Context Protocol (MCP) server that provides Claude with essential Appwrite integration. This version focuses on core functionality with action-based combined tools, offering database operations, user management, storage, messaging, and team management in an efficient package designed to stay under MCP context limits.

🚀 Features

🎯 Core Appwrite Operations:

• Database Management - Create, list, and delete databases
• Collection Operations - Full collection lifecycle management
• Document CRUD - Complete document operations with bulk support
• User Management - User operations including bulk processing and preferences
• Storage Management - Bucket and file operations with URL generation
• Team Management - Complete team administration
• Messaging Service - Messages, topics, and subscriber management
• Attribute & Index Management - Schema management with bulk operations
• Health Monitoring - System health checks

⚡ Action-Based Design:

• Single tools handle multiple operations using action parameters
• Bulk operations integrated into respective categories
• Context-optimized - 88% fewer tools than original
• Maintained functionality - All core features preserved

📦 Quick Start

1️⃣ Installation

# Clone the repository
git clone <repository-url>
cd appwrite-mcp-server

# Install dependencies
npm install

# Build the TypeScript code
npm run build

2️⃣ Configuration

Create a .env file in your current working directory (where you run Claude Code from):

# Copy the example file to your current working directory
cp /path/to/app-write-mcp/.env.example ./.env

Edit your .env file with your Appwrite credentials:

APPWRITE_PROJECT_ID=your-project-id-here
APPWRITE_API_ENDPOINT=https://cloud.appwrite.io/v1
APPWRITE_API_KEY=your-api-key-here

💡 Tip: The MCP server looks for .env in the directory where Claude Code is running, allowing different configurations for different projects.

3️⃣ Integration Options

Option A: Claude Code (CLI) Integration

# Add the MCP server to Claude Code
claude mcp add appwrite-mcp-server "C:\path\to\your\app-write-mcp\dist\index.js"

# Example with actual path
claude mcp add appwrite-mcp-server "C:\Users\moh12\app-write-mcp\dist\index.js"

Option B: Cursor IDE Integration

💡 Note: Cursor doesn't support .env files for MCP servers, so we pass environment variables directly in the configuration.

1. Open Command Palette (Ctrl/Cmd + Shift + P)

2. Type "Preferences: Open Settings (JSON)"

3. Add MCP Server Configuration to your settings.json:

   {
     "mcp.servers": {
       "appwrite-mcp-server": {
         "command": "node",
         "args": ["C:\\path\\to\\your\\app-write-mcp\\dist\\index.js"],
         "env": {
           "APPWRITE_PROJECT_ID": "your-project-id-here",
           "APPWRITE_API_ENDPOINT": "https://cloud.appwrite.io/v1",
           "APPWRITE_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

4. Replace the configuration values:

   • Path: Update C:\\path\\to\\your\\app-write-mcp\\dist\\index.js with your actual path
   • Project ID: Your Appwrite project ID
   • API Endpoint: Your Appwrite endpoint (Cloud or self-hosted)
   • API Key: Your Appwrite API key with required permissions

5. Example configuration:

   {
     "mcp.servers": {
       "appwrite-mcp-server": {
         "command": "node",
         "args": ["C:\\Users\\username\\app-write-mcp\\dist\\index.js"],
         "env": {
           "APPWRITE_PROJECT_ID": "6612345a000818bb9d2e",
           "APPWRITE_API_ENDPOINT": "https://cloud.appwrite.io/v1",
           "APPWRITE_API_KEY": "standard_1234567890abcdef..."
         }
       }
     }
   }
   

6. Save the file and restart Cursor to load the MCP server

Option C: Continue.dev Integration

1. Open your Continue configuration file (~/.continue/config.json)

2. Add the MCP server to your configuration:

   {
     "mcpServers": [
       {
         "name": "appwrite-mcp-server",
         "command": "node",
         "args": ["C:\\path\\to\\your\\app-write-mcp\\dist\\index.js"],
         "env": {
           "APPWRITE_PROJECT_ID": "your-project-id-here",
           "APPWRITE_API_ENDPOINT": "https://cloud.appwrite.io/v1",
           "APPWRITE_API_KEY": "your-api-key-here"
         }
       }
     ]
   }
   

3. Replace with your actual credentials (same as Cursor configuration above)

4. Restart your IDE to apply the changes

4️⃣ Verification

Once integrated, you should be able to use commands like:

• "List my Appwrite databases"
• "Create a new user with email test@example.com"
• "Show me all collections in my database"

🛠️ Available Tools (16 Total)

🗄️ Database Operations (1 tool)

Tool	Actions	Description
manage_database	create, list, delete	Comprehensive database management

📁 Collection Operations (1 tool)

Tool	Actions	Description
collection_operations	create, get, list, update, delete	Complete collection lifecycle management

🏷️ Attribute Management (1 tool)

Tool	Actions	Description
attribute_operations	create, get, list, update, delete, bulk_create, bulk_delete	Full attribute management with bulk operations

📊 Index Management (1 tool)

Tool	Actions	Description
index_operations	create, get, list, delete	Complete index management

📄 Document Operations (2 tools)

Tool	Actions/Description
document_operations	create, get, update, delete, bulk_create, bulk_update, bulk_delete
list_documents	List documents with advanced queries and pagination

👥 User Management (2 tools)

Tool	Actions/Description
user_operations	create, get, update, delete, update_preferences, update_labels, bulk_create, bulk_update, bulk_delete
list_users	List users with advanced filtering and pagination

🗂️ Storage Operations (3 tools)

Tool	Actions/Description
bucket_operations	create, get, list, update, delete
file_operations	get, create, update, delete, list
get_file_url	Generate download, preview, or view URLs with transformations

👨‍👩‍👧‍👦 Team Management (1 tool)

Tool	Actions	Description
team_operations	create, get, list, update, delete	Complete team management

📧 Messaging Operations (3 tools)

Tool	Actions	Description
messaging_message_operations	create, get, list, update, delete	Complete message management
messaging_topic_operations	create, get, list, update, delete	Complete topic management
messaging_subscriber_operations	create, get, list, delete	Complete subscriber management

🏥 Health Monitoring (1 tool)

Tool	Description
get_health	Get overall health status of Appwrite services

---

⚙️ Configuration Guide

🔑 Getting Appwrite Credentials

1. 🆔 Project ID: Found in your Appwrite console under Settings > General
2. 🌐 API Endpoint:
   • Appwrite Cloud: https://cloud.appwrite.io/v1
   • Self-hosted: https://your-domain.com/v1
3. 🔐 API Key: Create a new API key in your Appwrite console under Settings > API Keys
   • ✅ Required scopes: databases.read, databases.write, users.read, users.write, storage.read, storage.write, messages.read, messages.write, topics.read, topics.write, subscribers.read, subscribers.write, teams.read, teams.write, health.read

🎯 VS Official Implementation

Feature	Our Implementation	Official Appwrite MCP
Tools Available	🟢 16 optimized tools (context-efficient)	🟡 195 tools (selective enabling)
Context Usage	🟢 Under 25,000 tokens (88% reduction)	🔴 Over 60,000 tokens
Tool Design	🟢 Action-based combined tools	🟡 Individual tools for each operation
Core Operations	🟢 All essential Appwrite features	🟡 Database tools only (context limits)
Messaging Service	🟢 Messages, topics, subscribers	🟡 Selective enabling required
Storage Operations	🟢 Complete file operations & uploads	🟡 Basic bucket operations
User Management	🟢 CRUD + preferences + bulk operations	🟡 Basic CRUD only
Bulk Operations	🟢 Integrated into respective categories	🔴 Not available
Error Handling	🟢 Comprehensive	🟡 Basic
Language	🟡 TypeScript/Node.js	🟢 Python
Maintenance	🟢 Easier with fewer tools	🟡 Complex with many tools

🎯 Usage Examples

Once integrated, you can use natural language commands with Claude to interact with Appwrite:

🗄️ Database & Collection Management

✨ "Create a new database called 'ecommerce'"
✨ "List all my databases"
✨ "Create a collection called 'products' in the ecommerce database"
✨ "Show me all collections in the ecommerce database"
✨ "Delete the old 'test' database"

🏷️ Schema & Attributes

✨ "Create a string attribute called 'name' in the products collection" 
✨ "Add multiple attributes with bulk create operation"
✨ "List all attributes in the products collection"
✨ "Update attribute settings for existing fields"
✨ "Create a unique index on the 'sku' attribute"
✨ "Remove old attributes with bulk delete"

📄 Document Operations

✨ "Create a new product document with name 'iPhone 15' and price 999"
✨ "List all documents in the products collection"
✨ "Update document xyz123's price to 899"
✨ "Get document abc456 from the products collection"
✨ "Delete all out-of-stock products"

👥 User Management

✨ "Create a new user with email john@example.com"
✨ "List all users in the project with filtering"
✨ "Update user xyz123's name and email"
✨ "Update user labels for admin permissions"
✨ "Delete inactive user accounts"
✨ "Update user preferences for notifications"
✨ "Bulk create 10 test users for demo"
✨ "Bulk update user information from CSV"

🗂️ Storage & File Management

✨ "Create a new storage bucket for user uploads"
✨ "List all files in the images bucket"
✨ "Get download URL for file abc123"
✨ "Generate preview URL for image with 300x200 dimensions"
✨ "Get file view URL for document xyz456"
✨ "Delete old file from storage bucket"

📧 Messaging & Communication

✨ "List all messaging topics"
✨ "Create a topic for user announcements"
✨ "Add subscribers to the announcements topic"
✨ "Send a message to all subscribers"
✨ "List all messages and their delivery status"

🎬 Real-World Scenarios

E-commerce Setup:

1. "Create an ecommerce database"
2. "Create a products collection with attributes"
3. "Bulk create product documents from inventory"
4. "Set up user authentication for customers"
5. "Create indexes for search optimization"

Content Management:

1. "Create a blog database with posts and comments collections"
2. "Create string and datetime attributes for blog posts"
3. "List all blog posts with pagination"
4. "Update blog post content and metadata"

---

🔧 Development

# Build TypeScript to JavaScript
npm run build

# Watch mode for development
npm run dev

# Run the built server
npm start

🐛 Troubleshooting

Common Issues & Solutions

Issue	Solution
❌ Configuration not found	Make sure .env file exists in your working directory
❌ API Key issues	Ensure your API key has all required scopes enabled
❌ Connection failed	Verify your API endpoint is correct (check for typos)
❌ Tools not loading	Restart your IDE after adding the MCP server
❌ Permission denied	Check that your API key has databases.write, users.write permissions
❌ Schema validation errors	Use attribute_operations with list action to check collection schema

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details

---

⭐ Star this repo if it helped you!

Built with ❤️ for the Appwrite and Claude communities

Report Bug • Request Feature • Documentation