app-write-mcp/README.md

# 🚀 Appwrite MCP Server

<div align="center">

![Appwrite MCP](https://img.shields.io/badge/Appwrite-MCP-red?style=for-the-badge&logo=appwrite)
![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)
![Claude](https://img.shields.io/badge/Claude-AI-orange?style=for-the-badge)

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

</div>

---

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, and team management in an efficient package designed to stay under MCP context limits.

## 🚀 Features

**🎯 Core Appwrite Operations:**
- **Database Management** - Create, get, list, update, and delete databases with enabled status
- **Collection Operations** - Full collection lifecycle with document security and search support
- **Document CRUD** - Complete document operations with bulk support and advanced queries
- **User Management** - User operations including bulk processing and preferences
- **Storage Management** - Complete bucket operations with advanced configuration (file size limits, allowed extensions, compression, encryption, antivirus) and file upload/download
- **Team Management** - Team CRUD operations
- **Attribute & Index Management** - Schema management with array support and 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** - Efficient tool design for reduced token usage
- **Advanced features** - Document security, file download, bucket encryption, array attributes

## 📦 Quick Start

### 1️⃣ Installation

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

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# On Linux/macOS: Make the compiled file executable
chmod +x dist/index.js
```

### 2️⃣ Configuration

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

```bash
# 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:

```env
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

```bash
# 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:**
   ```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:**
   ```json
   {
     "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:**
   ```json
   {
     "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 (12 Total)

<details>
<summary><strong>🗄️ Database Operations (1 tool)</strong></summary>

| Tool | Actions | Description |
|------|---------|-------------|
| `manage_database` | create, get, list, update, delete | Comprehensive database management with enabled status |

</details>

<details>
<summary><strong>📁 Collection Operations (1 tool)</strong></summary>

| Tool | Actions | Description |
|------|---------|-------------|
| `collection_operations` | create, get, list, update, delete | Complete collection lifecycle with document security, enabled status, and search |

</details>

<details>
<summary><strong>🏷️ Attribute Management (1 tool)</strong></summary>

| Tool | Actions | Description |
|------|---------|-------------|
| `attribute_operations` | create, get, list, update, delete, bulk_create, bulk_delete | Full attribute management with array support and bulk operations |

</details>

<details>
<summary><strong>📊 Index Management (1 tool)</strong></summary>

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

</details>

<details>
<summary><strong>📄 Document Operations (2 tools)</strong></summary>

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

</details>

<details>
<summary><strong>👥 User Management (2 tools)</strong></summary>

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

</details>

<details>
<summary><strong>🗂️ Storage Operations (3 tools)</strong></summary>

| Tool | Actions/Description |
|------|--------------------|
| `bucket_operations` | create, get, list, update, delete - with advanced configuration (file size limits, allowed extensions, compression, encryption, antivirus) |
| `file_operations` | get, create, update, delete, list, download - with actual file download implementation |
| `get_file_url` | Generate download, preview, or view URLs with transformations |

</details>


<details>
<summary><strong>👨‍👩‍👧‍👦 Team Management (1 tool)</strong></summary>

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

</details>

<details>
<summary><strong>🏥 Health Monitoring (1 tool)</strong></summary>

| Tool | Description |
|------|-------------|
| `get_health` | Get overall health status of Appwrite services |

</details>

---


## ⚙️ 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`, `teams.read`, `teams.write`, `health.read`

### 🎯 VS Official Implementation

| Feature | Our Implementation | Official Appwrite MCP |
|---------|-------------------|----------------------|
| **Tools Available** | 🟢 12 optimized tools (context-efficient) | 🟡 195 tools (selective enabling) |
| **Context Usage** | 🟢 Optimized token usage | 🔴 Over 60,000 tokens |
| **Tool Design** | 🟢 Action-based combined tools | 🟡 Individual tools for each operation |
| **Core Operations** | 🟢 All essential database, user, storage, and team features | 🟡 Database tools only (context limits) |
| **Storage Operations** | 🟢 Complete file operations with download & advanced bucket config | 🟡 Basic bucket operations |
| **User Management** | 🟢 CRUD + preferences + bulk operations | 🟡 Basic CRUD only |
| **Advanced Features** | 🟢 Document security, file encryption, array attributes, compression | 🔴 Limited |
| **Bulk Operations** | 🟢 Integrated into respective categories | 🔴 Not available |
| **Error Handling** | 🟢 Comprehensive with validation | 🟡 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:

<details>
<summary><strong>🗄️ Database & Collection Management</strong></summary>

```
✨ "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"
```

</details>

<details>
<summary><strong>🏷️ Schema & Attributes</strong></summary>

```
✨ "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"
```

</details>

<details>
<summary><strong>📄 Document Operations</strong></summary>

```
✨ "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"
```

</details>

<details>
<summary><strong>👥 User Management</strong></summary>

```
✨ "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"
```

</details>

<details>
<summary><strong>🗂️ Storage & File Management</strong></summary>

```
✨ "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"
```

</details>






### 🎬 **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

```bash
# Build TypeScript to JavaScript
npm run build

# Watch mode for development
npm run dev

# Run the built server
npm start
```

## 🐛 Troubleshooting

<details>
<summary><strong>Common Issues & Solutions</strong></summary>

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

</details>

## 🤝 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](LICENSE) file for details

---

<div align="center">

**⭐ Star this repo if it helped you!**

Built with ❤️ for the Appwrite and Claude communities

[Report Bug](https://git.nebulm.com/smoido/app-write-mcp/issues) • [Request Feature](https://git.nebulm.com/smoido/app-write-mcp/issues) • [Documentation](https://git.nebulm.com/smoido/app-write-mcp/wiki)

</div>