An MCP server that wraps the official mcp-server-appwrite behind 4 smart tools instead of exposing hundreds of raw Appwrite tools directly to your AI agent.

New to MCP? Model Context Protocol is an open standard that lets AI assistants (Claude, Copilot, Cursor, etc.) call external tools. An MCP server is a small program that exposes those tools. This project is an MCP server for Appwrite — an open-source backend-as-a-service platform.

The Problem

The official mcp-server-appwrite registers one tool per Appwrite API endpoint — databases, storage, users, functions, messaging, teams, and more. That is a lot of tools. Most AI agents struggle with this because:

• Tool overload. Hundreds of tools flood the model's context and slow down tool selection.
• Context bloat. Each tool call returns verbose JSON that eats up the context window.
• No guardrails. Every tool is writable by default — one wrong call can delete a database.

How the Operator Fixes This

graph LR
    A[AI Agent] -->|4 tools| B[Appwrite Operator]
    B -->|stdio| C[mcp-server-appwrite]
    C --> D[Your Appwrite Project]

The operator sits between your AI agent and the raw Appwrite backend:

1. 4 public tools replace hundreds. The AI searches, calls, and investigates through a small, focused surface.
2. Large results stay out of context. Full responses are stored server-side and exposed as MCP Resources. The AI gets a short preview + a resource link it can fetch only when needed.
3. Write protection. Non-read-only tools require an explicit confirmWrite: true flag — the AI cannot accidentally mutate your data.
4. Smart search. Fuzzy, scored tool search with camelCase splitting, verb detection, and service filtering finds the right hidden tool fast.

Prerequisites

You need these installed on your machine before starting:

How to get your Appwrite credentials:

1. Go to your Appwrite console → Settings → copy your Project ID
2. Go to Settings → API Keys → create a key with the scopes you need → copy the API Key
3. Your Endpoint is https://cloud.appwrite.io/v1 for Appwrite Cloud, or https://your-domain/v1 for self-hosted

Quick Start

Step 1: Clone and build

git clone https://github.com/sgaabdu4/appwrite-operator.git
cd appwrite-operator
npm install
npm run build

Step 2: Run the tests (optional)

npm test

Step 3: Add to your MCP client

Pick one of the setups below depending on your client.

Setup

Option A: npx — Zero Install (Recommended)

No cloning, no building. Your MCP client downloads and runs the operator automatically.

Note: You still need Node.js 20+ and uv installed on your machine (see Prerequisites).

Claude Desktop — add to claude_desktop_config.json (find it via Claude Desktop → Settings → Developer → Edit Config):

{
  "mcpServers": {
    "appwrite-operator": {
      "command": "npx",
      "args": ["-y", "appwrite-operator-mcp"],
      "env": {
        "APPWRITE_PROJECT_ID": "your-project-id",
        "APPWRITE_API_KEY": "your-api-key",
        "APPWRITE_ENDPOINT": "https://cloud.appwrite.io/v1"
      }
    }
  }
}

VS Code — add to .vscode/mcp.json in your workspace, or open Command Palette → MCP: Open User Configuration:

{
  "servers": {
    "appwrite-operator": {
      "command": "npx",
      "args": ["-y", "appwrite-operator-mcp"],
      "env": {
        "APPWRITE_PROJECT_ID": "your-project-id",
        "APPWRITE_API_KEY": "your-api-key",
        "APPWRITE_ENDPOINT": "https://cloud.appwrite.io/v1"
      }
    }
  }
}

Cursor — add to Cursor Settings → MCP → Add Server:

{
  "mcpServers": {
    "appwrite-operator": {
      "command": "npx",
      "args": ["-y", "appwrite-operator-mcp"],
      "env": {
        "APPWRITE_PROJECT_ID": "your-project-id",
        "APPWRITE_API_KEY": "your-api-key",
        "APPWRITE_ENDPOINT": "https://cloud.appwrite.io/v1"
      }
    }
  }
}

Replace your-project-id, your-api-key, and https://cloud.appwrite.io/v1 with your actual Appwrite credentials. The operator spawns uvx mcp-server-appwrite automatically.

Option B: Clone and Build (Local Development)

If you want to modify the operator or run from source:

git clone https://github.com/sgaabdu4/appwrite-operator.git
cd appwrite-operator
npm install
npm run build

Then use node instead of npx in your MCP client config:

{
  "command": "node",
  "args": ["/absolute/path/to/appwrite-operator/build/src/index.js"],
  "env": {
    "APPWRITE_PROJECT_ID": "your-project-id",
    "APPWRITE_API_KEY": "your-api-key",
    "APPWRITE_ENDPOINT": "https://cloud.appwrite.io/v1"
  }
}

Option C: Config File (Multiple Backends)

For advanced setups with multiple Appwrite projects or custom backend commands, create a config file:

appwrite-operator.config.json:

{
  "backends": [
    {
      "id": "production",
      "label": "Production",
      "command": "uvx",
      "args": ["--with", "appwrite<16.0.0", "mcp-server-appwrite"],
      "env": {
        "APPWRITE_PROJECT_ID": "${PROD_PROJECT_ID}",
        "APPWRITE_API_KEY": "${PROD_API_KEY}",
        "APPWRITE_ENDPOINT": "${PROD_ENDPOINT}"
      }
    },
    {
      "id": "staging",
      "label": "Staging",
      "command": "uvx",
      "args": ["--with", "appwrite<16.0.0", "mcp-server-appwrite"],
      "env": {
        "APPWRITE_PROJECT_ID": "${STAGING_PROJECT_ID}",
        "APPWRITE_API_KEY": "${STAGING_API_KEY}",
        "APPWRITE_ENDPOINT": "${STAGING_ENDPOINT}"
      }
    }
  ]
}

.env (values for ${...} placeholders above):

PROD_PROJECT_ID=abc123
PROD_API_KEY=secret-key-here
PROD_ENDPOINT=https://cloud.appwrite.io/v1
STAGING_PROJECT_ID=xyz789
STAGING_API_KEY=staging-key-here
STAGING_ENDPOINT=https://staging.appwrite.io/v1

Then point the operator at these files via environment variables:

{
  "mcpServers": {
    "appwrite-operator": {
      "command": "npx",
      "args": ["-y", "appwrite-operator-mcp"],
      "env": {
        "APPWRITE_OPERATOR_CONFIG": "/absolute/path/to/appwrite-operator.config.json",
        "APPWRITE_OPERATOR_ENV": "/absolute/path/to/.env"
      }
    }
  }
}

Tools

The operator exposes 4 tools. Your AI agent uses them in this workflow:

graph TD
    A[appwrite_search_tools] -->|find the right tool| B[appwrite_call_tool]
    A -->|or run a multi-step plan| C[appwrite_investigate]
    D[appwrite_list_backends] -->|check connectivity| A

appwrite_list_backends

List configured Appwrite backends and their connection status.

Example response:

- production (Production), connected, tools=422, 14 services

appwrite_search_tools

Search the hidden Appwrite tool catalog by natural language query. Returns scored matches with resource links to the full catalog.

Example response:

1. [98] tablesdb_list_rows (production) — read
   List rows from a TablesDB table.
   Required: databaseId, collectionId

appwrite_call_tool

Call a specific hidden Appwrite tool by name. Pass tool parameters in the arguments field.

Write protection: If the tool is classified as write, delete, or unknown and confirmWrite is not true, the call is blocked with an error message.

Large results: When a response exceeds 800 characters, the AI gets a short preview and a resource link (operator://results/{id}) to fetch the full result on demand. This keeps the context window clean.

appwrite_investigate

Plan and run a bounded, read-only investigation across your Appwrite project. The operator builds a multi-step plan, executes each step, and returns a summary.

How planning works: If your MCP client supports sampling, the operator asks the AI to build an optimal plan. Otherwise, it falls back to deterministic heuristic planning (fuzzy search + verb detection + argument matching).

Resources

The operator exposes 3 MCP resources that keep large data out of the AI's context until it actually needs it:

These are returned as resource_link references in tool responses. The AI fetches them only when it needs the full data.

Contributing

See CONTRIBUTING.md for development setup, architecture, and release process.

Troubleshooting

"No Appwrite backends configured" → Check that APPWRITE_PROJECT_ID, APPWRITE_API_KEY, and APPWRITE_ENDPOINT are set in your MCP client config, or that APPWRITE_OPERATOR_CONFIG points to a valid config file.

"Backend failed to connect" → Make sure uvx is installed and accessible from your PATH. Run uvx mcp-server-appwrite --help to verify.

"Write blocked" error on appwrite_call_tool → The tool is classified as a write/delete operation. Add confirmWrite: true to allow it.

Large responses seem truncated → The operator returns a preview (first 800 chars) and a resource link. Your MCP client should fetch the full result via operator://results/{id}.

License

MIT