smoido/app-write-mcp
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3c763fc44f67e282e7efae8d6bb032e1f108c650
app-write-mcp/README.md
smoido 7084a7d5b2 down to 16 general tools only
2025-09-05 05:09:13 +03:00

18 KiB
Raw Blame History

🚀 Appwrite MCP Server

Appwrite MCP TypeScript Claude

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
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 (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

🗑️ Removed Features

The following features have been removed to optimize context usage:

  • Data Analysis Tools - Auto-detect schemas, duplicate detection, data quality analysis
  • Avatars Service - Icon generation, QR codes, initials avatars
  • Locale Service - Countries, currencies, languages, timezones
  • Advanced User Features - MFA management, identity management, email/phone verification (labels management retained in user_operations)
  • Function Management - Function deployments, execution, variables
  • Messaging Providers - Provider configuration and management
  • Session Management - User session create/delete/list
  • Advanced Health Monitoring - Specific service health checks

These features are preserved in removed-tools-backup.ts for future restoration if needed.

⚙️ 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"
✨ "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 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