Appwrite MCP server_

Appwrite offers a Model Context Protocol (MCP) server that allows LLMs to directly interact with Appwrite's API and docs. Using the MCP server, you can use applications such as Claude Code, Codex, Cursor, Claude Desktop, and others to operate on your Appwrite project as well as gain context about the latest updates to Appwrite's SDKs, APIs, and CLI.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables Large Language Models (LLMs) and AI code-generation tools to interact with APIs and documentation in a structured manner. MCP servers provide a bridge between LLMs and external services, allowing them to perform actions such as querying databases, managing users, and accessing files.

The key benefits of using MCP servers include:

• Enhanced capabilities: LLMs can perform complex tasks by interacting with APIs, going beyond simple text generation.
• Improved context: By accessing up-to-date documentation and API definitions, LLMs can provide more accurate and relevant responses.
• Seamless integration: MCP servers can be easily integrated with popular AI tools and code editors, enhancing their functionality.

Why use the Appwrite MCP server?

Some popular use cases for the Appwrite MCP server include:

• Code generation: Automatically generate code snippets or entire files based on user input and context.
• Documentation lookup: Quickly find relevant documentation for specific API endpoints or SDK features.
• Project management: Create, update, or delete resources in your Appwrite project using natural language commands.
• Debugging assistance: Get help with debugging issues by providing context about your project and recent changes.
• Learning and exploration: Explore Appwrite's features and capabilities through interactive conversations with LLMs.

The server also provides:

• Direct API interaction: Enables LLMs to perform actions directly on your Appwrite project
• Real-time data access: Allows LLMs to fetch and manipulate live data from your Appwrite instance
• Documentation search: Lets LLMs semantically search the Appwrite documentation for accurate, up-to-date context
• Events: Lets agents subscribe to changes in your project, such as new users or failed executions, and react when they happen. See Events
• Automatic service discovery: All supported Appwrite services are automatically registered, no configuration needed
• No local setup: Runs as a hosted HTTP service, so there is nothing to install or keep updated

Connection details

The Appwrite MCP server is a remote server that uses the HTTP transport. It is available at the following URL:

https://mcp.appwrite.io/

The server uses OAuth for authentication. When you add the server to an AI tool and connect for the first time, your browser opens so you can sign in to your Appwrite account and authorize access. You don't need to create or manage API keys.

MCP clients complete that OAuth flow with a localhost callback URL. If you run your AI tool on a remote host, follow Authenticate from a remote machine.

Pre-requisites

Before connecting to the MCP server, you must set up an Appwrite project on Appwrite Cloud. No additional software needs to be installed on your system.

Installation

You can add the MCP server to various AI tools and code editors:

Claude Code

ChatGPT

Codex

Cursor

Claude Desktop

Zenflow

VS Code

Zed

OpenCode

Google Antigravity

Grok Build

Pi

How it works

The MCP server starts in a compact workflow where only a small set of MCP tools is exposed to the model:

• appwrite_get_context - Returns a summary of your workspace, including your account, organization, and projects
• appwrite_search_tools - Searches the full Appwrite tool catalog at runtime
• appwrite_call_tool - Calls a specific Appwrite tool by name
• appwrite_search_docs - Semantically searches the Appwrite documentation

The full Appwrite tool catalog stays internal and is searched at runtime, using less of the model's context.

Events

The MCP server supports MCP Events, an extension to the Model Context Protocol. An agent subscribes to an event in your project, and the server sends the agent each matching event as it happens, so the agent does not need to poll.

Events require an MCP client that supports the extension. Pi supports it through the pi-mcp-events extension.

Available events

Every event requires a project_id, and each subscription covers only the project and resource you name.

Payloads contain IDs and metadata only, never row contents, emails, phone numbers, request headers, or execution logs. The agent fetches other details with tool calls, which go through Appwrite's permission checks.

Delivery

The server supports both delivery modes in the proposal:

• Push (events/stream): for agents that run on your machine and have no public URL. The agent keeps one request open, and the server streams events on it with a heartbeat every 25 seconds. While the stream is open, the server renews the subscription every 2 minutes. If you lose access to the resource or the resource is deleted, the stream ends with an error.
• Webhook (events/subscribe): for clients with a public HTTPS endpoint. The server verifies the endpoint with a challenge, then sends each event as a POST signed with Standard Webhooks. A subscription lasts 1 hour by default, or between 5 minutes and 24 hours on request. The client must refresh it before it expires.

How subscriptions work

The server keeps no subscription state of its own. Each subscription is an Appwrite webhook in the subscribed project, created with your OAuth token:

1. When you subscribe, the server creates a webhook that listens for the matching Appwrite events.
2. The subscription details, such as the event, its arguments, the delivery target, and the expiry, are encrypted and stored on the webhook. Appwrite returns them with each webhook call.
3. On each call, the server verifies Appwrite's signature, decrypts the subscription, checks the expiry, and keeps only the fields that the event declares.
4. The server delivers the event on the open stream for push delivery, or as a signed POST to the callback for webhook delivery.

These webhooks are named MCP events or MCP events push in the Appwrite Console. The server deletes a webhook when you unsubscribe or close the stream. If a client disconnects without unsubscribing, its webhook expires and is removed the next time you subscribe.

Permissions

• Subscriptions use the same OAuth sign-in as the other tools, plus the webhook scopes.
• The server checks your access to the watched resource when you subscribe and on every renewal.
• A project you cannot access returns the same error as a project that does not exist.
• Event payloads are external data. pi-mcp-events passes them to the model as data, not as instructions.

Limits

• Each active subscription or open stream uses one webhook in the project. The Free plan allows 2 webhooks per project, and Pro allows unlimited webhooks. At the limit, subscribing returns an error.
• Each user can keep up to 25 streams open on each server instance.
• Events that occur while a stream reconnects are not replayed. After a reconnect, have the agent check the current state.

Use events with Pi

1. Install the MCP adapter and the events extension:

   Bash

   Copy

   pi install npm:pi-mcp-adapter@^5.1.0
   pi install npm:@realmikekelly/pi-mcp-events@^0.2.0

2. Add the Appwrite MCP server to ~/.pi/agent/mcp-adapter.json:

   JSON

   Copy

   {
     "mcpServers": {
       "appwrite": {
         "url": "https://mcp.appwrite.io/",
         "auth": "oauth"
       }
     }
   }

3. Start Pi with pi and sign in to Appwrite when your browser opens.

4. Ask Pi to subscribe:

   Plain text

   Copy

   Subscribe with mcp_events to users.user.created on the appwrite server for project_id <PROJECT_ID>, then finish your turn and wait. Whenever an event arrives, look up that user and tell me their name and email.

When a user is created in the project, Pi receives the event without a new prompt and reports the user's name and email.

Authenticate from a remote machine

MCP clients listen on a localhost callback URL for the OAuth redirect. When the client runs over SSH, on a droplet, or on any host without a local browser, that callback stays on the remote machine's loopback.

Log in from the Claude Code shell with --no-browser:

claude mcp login appwrite --no-browser

The command prints an authorization URL. Open it in a browser on your local machine, sign in to Appwrite, and authorize access. After you approve, the browser navigates to a http://localhost:.../callback URL. Copy the full URL from the address bar and paste it into the Claude Code prompt.

Self-hosted Appwrite

The hosted MCP server authenticates against Appwrite Cloud. If you are running a self-hosted Appwrite instance, use the local MCP server instead. It runs on your machine over the stdio transport and connects to your instance with an API key. Follow the self-hosted MCP server documentation to set it up.

Usage

Once configured, your AI assistant will have access to your Appwrite project. You can ask questions like:

Example 1: List users

Run the following prompt in your preferred code editor/LLM after enabling the MCP server:

List users in my Appwrite project

Example 2: Search a site

Run the following prompt in your preferred code editor/LLM after enabling the MCP server:

Get the details of my portfolio site from Appwrite

Example 3: Create a user

Run the following prompt in your preferred code editor/LLM after enabling the MCP server:

Add a user john.doe@example.com to the Appwrite project

Example 4: Search the documentation

Run the following prompt in your preferred code editor/LLM after enabling the MCP server:

Show me how to set up real-time subscriptions that trigger on creation of a user