mcp-server-appwrite 0.4.1

MCP (Model Context Protocol) server for Appwrite

Appwrite MCP server

mcp-name: io.github.appwrite/mcp-for-api

Overview

A Model Context Protocol server for interacting with Appwrite's API. This server provides tools to manage databases, users, functions, teams, and more within your Appwrite project.

Quick Links

• Configuration
• Installation
• IDE Integration:
  • Claude Desktop
  • Cursor
  • Windsurf Editor
  • VS Code
• Local Development
• Debugging

Configuration

Before launching the MCP server, you must setup an Appwrite project and create an API key with the necessary scopes enabled.

The server validates the credentials and scopes required for its built-in Appwrite service set during startup. If the endpoint, project ID, API key, or scopes are wrong, the MCP server will fail to start instead of waiting for the first tool call to fail.

Create a .env file in your working directory and add the following:

APPWRITE_PROJECT_ID=your-project-id
APPWRITE_API_KEY=your-api-key
APPWRITE_ENDPOINT=https://<REGION>.cloud.appwrite.io/v1

Then, open your terminal and run the following command

Linux and MacOS

source .env

Windows

Command Prompt

for /f "tokens=1,2 delims==" %A in (.env) do set %A=%B

PowerShell

Get-Content .\.env | ForEach-Object {
  if ($_ -match '^(.*?)=(.*)$') {
    [System.Environment]::SetEnvironmentVariable($matches[1], $matches[2], "Process")
  }
}

Installation

Using uv (recommended)

When using uv no specific installation is needed. We will use uvx to directly run mcp-server-appwrite.

uvx mcp-server-appwrite

Using pip

pip install mcp-server-appwrite

Then run the server using

python -m mcp_server_appwrite

Tool surface

The server no longer accepts service-selection or mode flags. It always starts in a compact workflow so the MCP client only sees a small operator-style surface while the full Appwrite catalog stays internal.

• Only 2 MCP tools are exposed to the model:
  • appwrite_search_tools
  • appwrite_call_tool
• The full Appwrite tool catalog stays internal and is searched at runtime.
• Large tool outputs are stored as MCP resources and returned as preview text plus a resource URI.
• Mutating hidden tools require confirm_write=true.
• The server automatically registers all supported Appwrite services except the legacy Databases API.

If you still have older MCP configs that pass flags such as --mode or --users, remove them.

Usage with Claude Desktop

In the Claude Desktop app, open the app's Settings page (press CTRL + , on Windows or CMD + , on MacOS) and head to the Developer tab. Clicking on the Edit Config button will take you to the claude_desktop_config.json file, where you must add the following:

{
  "mcpServers": {
    "appwrite": {
      "command": "uvx",
      "args": [
        "mcp-server-appwrite"
      ],
      "env": {
        "APPWRITE_PROJECT_ID": "<YOUR_PROJECT_ID>",
        "APPWRITE_API_KEY": "<YOUR_API_KEY>",
        "APPWRITE_ENDPOINT": "https://<REGION>.cloud.appwrite.io/v1" // Optional
      }
    }
  }
}

Note: In case you see a uvx ENOENT error, ensure that you either add uvx to the PATH environment variable on your system or use the full path to your uvx installation in the config file.

Upon successful configuration, you should be able to see the server in the list of available servers in Claude Desktop.

Usage with Cursor

Head to Cursor Settings > MCP and click on Add new MCP server. Choose the type as Command and add the command below to the Command field.

• MacOS

env APPWRITE_API_KEY=your-api-key env APPWRITE_PROJECT_ID=your-project-id uvx mcp-server-appwrite

• Windows

cmd /c SET APPWRITE_PROJECT_ID=your-project-id && SET APPWRITE_API_KEY=your-api-key && uvx mcp-server-appwrite

Usage with Windsurf Editor

Head to Windsurf Settings > Cascade > Model Context Protocol (MCP) Servers and click on View raw config. Update the mcp_config.json file to include the following:

{
  "mcpServers": {
    "appwrite": {
      "command": "uvx",
      "args": [
        "mcp-server-appwrite"
      ],
      "env": {
        "APPWRITE_PROJECT_ID": "<YOUR_PROJECT_ID>",
        "APPWRITE_API_KEY": "<YOUR_API_KEY>",
        "APPWRITE_ENDPOINT": "https://<REGION>.cloud.appwrite.io/v1" // Optional
      }
    }
  }
}

Usage with VS Code

Configuration

1. Update the MCP configuration file: Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and run MCP: Open User Configuration. It should open the mcp.json file in your user settings.

2. Add the Appwrite MCP server configuration: Add the following to the mcp.json file:

{
  "servers": {
    "appwrite": {
      "command": "uvx",
      "args": ["mcp-server-appwrite"],
      "env": {
        "APPWRITE_PROJECT_ID": "<YOUR_PROJECT_ID>",
        "APPWRITE_API_KEY": "<YOUR_API_KEY>",
        "APPWRITE_ENDPOINT": "https://<REGION>.cloud.appwrite.io/v1"
      }
    }
  }
}

3. Start the MCP server: Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and run MCP: List Servers. In the dropdown, select appwrite and click on the Start Server button.

4. Use in Copilot Chat: Open Copilot Chat and switch to Agent Mode to access the Appwrite tools.

Local Development

Clone the repository

git clone https://github.com/appwrite/mcp-for-api.git

Install uv

• Linux or MacOS

curl -LsSf https://astral.sh/uv/install.sh | sh

• Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Prepare virtual environment

First, create a virtual environment.

uv venv

Next, activate the virtual environment.

• Linux or MacOS

source .venv/bin/activate

• Windows

.venv\Scripts\activate

Run the server

uv run -v --directory ./ mcp-server-appwrite

Testing

Unit tests

uv run python -m unittest discover -s tests/unit -v

Live integration tests

These tests create and delete real Appwrite resources against a real Appwrite project. They run automatically when valid Appwrite credentials are available in the environment or .env.

uv run --extra integration python -m unittest discover -s tests/integration -v

Debugging

You can use the MCP inspector to debug the server.

npx @modelcontextprotocol/inspector \
  uv \
  --directory . \
  run mcp-server-appwrite

Make sure your .env file is properly configured before running the inspector. You can then access the inspector at http://localhost:5173.

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.