smoido/app-write-mcp
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0a362b37b184e8113db237c35ffb4242d8c02650
app-write-mcp/README.md
smoido 1ebc34764b added 68 tools
2025-07-27 18:12:02 +03:00

25 KiB
Raw Blame History

🚀 Appwrite MCP Server

Appwrite MCP TypeScript Claude

Transform Claude into your intelligent Appwrite management assistant
135 powerful tools • Complete API coverage • Full Messaging & Locale Services • Production-ready

A comprehensive Model Context Protocol (MCP) server that supercharges Claude with native Appwrite integration. Unlike the official implementation, this version includes advanced features like bulk operations, automatic schema validation, complete user management with MFA, storage file operations, function deployments & variables, full messaging service (topics, subscribers, providers), locale & avatars services, and comprehensive error handling.

🚀 Features

Core Appwrite Management:

  • Complete database and collection operations
  • Document CRUD with full query support
  • Advanced user management with MFA, identities, preferences
  • Storage buckets and comprehensive file operations
  • Serverless function management with deployments & variables
  • Team and permission management
  • Complete messaging service (providers, messages, topics, subscribers)
  • Locale service (countries, currencies, languages, timezones)
  • Avatars service (icons, QR codes, initials, favicons)

🧠 Intelligent Database Assistant:

  • Auto-detect schemas from sample data
  • Data quality analysis and recommendations
  • Duplicate detection with similarity matching
  • Index optimization suggestions
  • Schema migrations with safety checks

🔐 Advanced Authentication & Sessions:

  • Session management (create, delete, list user sessions)
  • Function execution with logging and monitoring
  • Health monitoring for all Appwrite services

⚡ Bulk Operations:

  • Bulk user management (create, update, delete multiple users)
  • Bulk document operations (create, update, delete multiple documents)
  • Efficient batch processing with detailed success/error reporting

📦 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 (135 Total)

🗄️ Database Operations (3 tools)
Tool Description
create_database Create a new database
list_databases List all databases in your project
delete_database Delete a database
📁 Collection Operations (4 tools)
Tool Description
create_collection Create a new collection in a database
get_collection ✨ Get collection details by ID
list_collections List all collections in a database
delete_collection Delete a collection from a database
🏷️ Attribute Management (5 tools)
Tool Description
create_attribute ✨ Create any attribute type (string, integer, float, boolean, datetime, email, IP, URL, enum, relationship)
get_attribute ✨ Get attribute details by key
update_attribute ✨ Update any attribute type with unified interface
list_attributes List all attributes in a collection
delete_attribute Delete an attribute from a collection
📊 Index Management (4 tools)
Tool Description
create_index Create an index in a collection (key, fulltext, unique)
get_index ✨ Get index details by key
list_indexes List all indexes in a collection
delete_index Delete an index from a collection
📄 Document Operations (5 tools)
Tool Description
create_document Create a new document in a collection ✨ with schema validation
get_document Get a document by ID
list_documents List documents in a collection with optional queries
update_document Update a document
delete_document Delete a document
👥 User Management (25 tools)
Tool Description
create_user Create a new user
list_users ✨ List all users with email/phone verification columns
get_user Get a user by ID
update_user_email Update user email
update_user_name Update user name
update_user_password Update user password
update_user_password_hash ✨ Update password with specific hash algorithm
delete_user Delete a user
verify_user_email ✨ Verify a user's email address
unverify_user_email ✨ Unverify a user's email address
verify_user_phone ✨ Verify a user's phone number
unverify_user_phone ✨ Unverify a user's phone number
update_user_mfa ✨ Enable/disable MFA for users
create_user_mfa_recovery_codes ✨ Generate MFA recovery codes
update_user_phone_verification ✨ Update phone verification status
update_user_labels ✨ Update user labels for permissions
get_user_preferences ✨ Get user preferences
update_user_preferences ✨ Update user preferences
list_user_identities ✨ List user identities
delete_user_identity ✨ Delete user identity
create_user_target ✨ Create messaging targets
list_user_targets ✨ List messaging targets
get_user_target ✨ Get messaging target details
update_user_target ✨ Update messaging target
delete_user_target ✨ Delete messaging target
🗂️ Storage Operations (13 tools)
Tool Description
create_bucket Create a storage bucket
list_buckets List all storage buckets
get_bucket Get a bucket by ID
update_bucket Update a storage bucket
delete_bucket Delete a storage bucket
list_files List files in a storage bucket
get_file ✨ Get file details by ID
create_file ✨ Upload file to storage bucket
update_file ✨ Update file metadata
get_file_download ✨ Get file download URL
get_file_preview ✨ Get file preview URL with image transformations
get_file_view ✨ Get file view URL
delete_file ✨ Delete a file
⚡ Function Management (14 tools)
Tool Description
create_function Create a new serverless function
list_functions List all functions
get_function Get a function by ID
update_function Update a function
delete_function Delete a function
list_function_deployments ✨ List function deployments
get_function_deployment ✨ Get deployment details
update_function_deployment ✨ Update deployment status
delete_function_deployment ✨ Delete deployment
create_function_variable ✨ Create function variables
list_function_variables ✨ List function variables
get_function_variable ✨ Get variable details
update_function_variable ✨ Update variables
delete_function_variable ✨ Delete variables
👨‍👩‍👧‍👦 Team Management (5 tools)
Tool Description
create_team Create a new team
list_teams List all teams
get_team Get a team by ID
update_team Update a team
delete_team Delete a team
📧 Messaging Operations (20 tools)
Tool Description
create_messaging_provider ✨ Create messaging provider
list_messaging_providers ✨ List messaging providers
get_messaging_provider ✨ Get messaging provider details
update_messaging_provider ✨ Update messaging provider
delete_messaging_provider ✨ Delete messaging provider
create_messaging_message ✨ Create and send message
list_messaging_messages ✨ List messages
get_messaging_message ✨ Get message details
update_messaging_message ✨ Update message
delete_messaging_message ✨ Delete message
create_messaging_topic ✨ Create messaging topic
list_messaging_topics ✨ List messaging topics
get_messaging_topic ✨ Get topic details
update_messaging_topic ✨ Update topic
delete_messaging_topic ✨ Delete topic
create_messaging_subscriber ✨ Create topic subscriber
list_messaging_subscribers ✨ List topic subscribers
get_messaging_subscriber ✨ Get subscriber details
delete_messaging_subscriber ✨ Delete subscriber
🌍 Locale Operations (5 tools)
Tool Description
list_countries ✨ List all countries with phone codes
list_continents ✨ List all continents
list_currencies ✨ List all currencies
list_languages ✨ List all languages
list_phone_codes ✨ List phone codes for countries
🎨 Avatars Operations (7 tools)
Tool Description
get_browser_icon ✨ Get browser icon URL
get_credit_card_icon ✨ Get credit card icon URL
get_favicon ✨ Get website favicon URL
get_flag_icon ✨ Get country flag icon URL
get_image_from_url ✨ Transform image from URL
get_initials_avatar ✨ Generate initials avatar URL
get_qr_code ✨ Generate QR code URL

🌟 Exclusive Advanced Features

🧠 Smart Schema Operations (4 tools)
Tool Description
auto_detect_schema ✨ Analyze sample data and automatically create collection schema
suggest_indexes ✨ Recommend optimal indexes based on collection usage patterns
validate_document ✨ Check document data against collection schema before creation
schema_migration ✨ Automatically migrate collection schema with data preservation
📊 Data Analysis & Insights (4 tools)
Tool Description
analyze_collection ✨ Get comprehensive data insights and patterns from collections
detect_duplicates ✨ Find potential duplicate records with similarity scoring
data_quality_check ✨ Analyze data quality (completeness, validity, consistency)
usage_stats ✨ Get usage statistics and access patterns for collections
🔐 Authentication & Sessions (3 tools)
Tool Description
create_session ✨ Create a new user session with email and password
delete_session ✨ Delete a user session
list_sessions ✨ List all sessions for a user
⚡ Function Execution (3 tools)
Tool Description
execute_function ✨ Execute a function with optional data
list_executions ✨ List function executions with logs
get_execution ✨ Get details of a specific function execution
🏥 Health Monitoring (3 tools)
Tool Description
get_health ✨ Get overall health status of Appwrite services
get_health_db ✨ Get database health status
get_health_storage ✨ Get storage health status
⚡ Bulk Operations (8 tools)
Tool Description
bulk_create_attributes ✨ Create multiple attributes at once in a collection
bulk_delete_attributes ✨ Delete multiple attributes at once from a collection
bulk_create_users ✨ Create multiple users at once
bulk_update_users ✨ Update multiple users at once
bulk_delete_users ✨ Delete multiple users at once
bulk_create_documents ✨ Create multiple documents at once
bulk_update_documents ✨ Update multiple documents at once
bulk_delete_documents ✨ Delete multiple documents at once

✨ Exclusive features not available in the official Appwrite MCP implementation

⚙️ 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
    • ✅ Enable all scopes for full functionality
    • ⚠️ Required scopes: databases.read, databases.write, users.read, users.write, functions.read, functions.write, storage.read, storage.write, targets.read, targets.write, providers.read, providers.write, messages.read, messages.write, topics.read, topics.write, subscribers.read, subscribers.write, locale.read, avatars.read, health.read

🎯 VS Official Implementation

Feature Our Implementation Official Appwrite MCP
Tools Available 🟢 135 tools (complete coverage) 🟡 195 tools (selective enabling)
Default Setup 🟢 Complete coverage out-of-box 🟡 Database tools only (context limits)
Messaging Service 🟢 Complete (providers, messages, topics, subscribers) 🟡 Selective enabling required
Locale & Avatars 🟢 Complete internationalization support 🟡 Selective enabling required
Storage Operations 🟢 Complete file operations & uploads 🟡 Basic bucket operations
User Management 🟢 MFA, identities, preferences, targets 🟡 Basic CRUD only
Functions Service 🟢 Deployments & variables included 🟡 Basic function management
Bulk Operations 🟢 Full support 🔴 Not available
Schema Validation 🟢 Automatic 🔴 Manual only
Error Handling 🟢 Comprehensive 🟡 Basic
Language 🟡 TypeScript/Node.js 🟢 Python
Context Efficiency 🟡 All tools use context 🟢 Selective loading saves context
Self-Hosted Focus 🟢 Optimized for self-hosted 🟡 Cloud-first approach

🎯 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 with max size 255"
✨ "Add a boolean attribute 'in_stock' to the products collection"
✨ "Create an enum attribute 'status' with values active, inactive, pending"
✨ "Add a relationship attribute linking products to categories"
✨ "Bulk create attributes: name (string), price (float), in_stock (boolean)"
✨ "Bulk delete attributes: old_field1, deprecated_field2, unused_field3"
✨ "List all attributes in the products collection"
✨ "Create a unique index on the 'sku' attribute"
📄 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 & Authentication 
✨ "Create a new user with email john@example.com and password SecurePass123"
✨ "List all users in the project"
✨ "Update user xyz123's name to 'John Doe'"
✨ "Verify user abc123's email address"
✨ "Enable MFA for user xyz123"
✨ "Generate MFA recovery codes for user abc456"
✨ "Update user labels for permissions: ['admin', 'moderator']"
✨ "Get user preferences for user xyz123"
✨ "Create messaging target for user notifications"
✨ "List all identities for user abc123"
✨ "Create a session for user john@example.com"
✨ "Bulk create 10 test users for demo purposes"
🗂️ 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"
⚡ Functions & Deployments 
✨ "Create a new function for email processing"
✨ "List all deployments for function abc123"
✨ "Create function variable API_KEY with secret value"
✨ "Update function variable to new value"
✨ "List all variables for function xyz456"
✨ "Execute function with user data payload"
🚀 Advanced Features (Exclusive) 
🚀 "Create a complete product schema with string, enum, float, and relationship attributes"
🚀 "Bulk create 10 attributes at once for my e-commerce collection"
🚀 "Add a relationship attribute linking orders to customers with two-way binding"
🚀 "Create an enum attribute for user roles with admin, user, moderator values"
🚀 "Analyze this sample data and create a collection schema automatically"
🚀 "Suggest optimal indexes for my users collection based on usage"
🚀 "Validate this document data before creating it"
🚀 "Find duplicate records in my customers collection"
🚀 "Check the data quality of my orders collection"
🚀 "Bulk create 100 user accounts from this CSV data"
🚀 "Execute the 'sendWelcomeEmail' function with user data"
🚀 "Show me the health status of all Appwrite services"
📧 Messaging & Communication 
✨ "Create a messaging provider for email notifications"
✨ "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"
🌍 Internationalization & Locale 
✨ "List all supported countries"
✨ "Get phone codes for all countries"
✨ "Show me all available currencies"
✨ "List all supported languages"
✨ "Get continent information"
🎨 Avatars & Visual Content 
✨ "Generate QR code for this URL"
✨ "Get flag icon for United States"
✨ "Create initials avatar for John Doe"
✨ "Get favicon for google.com"
✨ "Generate browser icon for Chrome"
✨ "Get credit card icon for Visa"

🎬 Real-World Scenarios

E-commerce Setup:

1. "Create an ecommerce database"
2. "Auto-detect schema from this product sample data"
3. "Bulk import 500 products from my 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. "Validate my blog post structure before saving"
3. "Find duplicate content across my posts"
4. "Analyze user engagement patterns"

🔧 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 list_attributes to check collection schema before creating documents

🤝 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