Skip to content

self-hosted.md

Latest commit

 

History

History
224 lines (181 loc) · 5.97 KB

self-hosted.md

File metadata and controls

224 lines (181 loc) · 5.97 KB
Raw

Self-hosted Appwrite

Running your own Appwrite instance? Run the MCP server locally over stdio and authenticate with a project API key instead of OAuth.

The local API-key catalog is intentionally smaller than the hosted OAuth catalog: it exposes 720 project-key-compatible methods across 27 services. DocumentsDB, VectorsDB, and text embeddings are available, but console control-plane services such as organizations, domains, projects, billing, migrations, dedicated databases, usage administration, VCS administration, and WAF administration are hidden because project API keys cannot authenticate those routes.

Setup

  1. In your Appwrite Console, create a project API key with the scopes you want the server to use.
  2. Add the server to your client using the config below, replacing the placeholders:
    • <YOUR_PROJECT_ID> — your Appwrite project ID.
    • <YOUR_API_KEY> — the API key you just created.
    • <YOUR_APPWRITE_DOMAIN> — your instance domain, e.g. localhost:9501 for a local Docker setup.

Self-hosted runs use uvx, so make sure uv is installed and on your PATH. stdio is the default transport for the package command. The server validates the endpoint, project ID, API key, and at least one supported service at startup, and fails before accepting tool calls if anything is wrong.

If your MCP client reports a reconnect failure such as Cursor -32000, the stdio process exited before the handshake — usually bad credentials, a wrong endpoint, or an API key missing every readable scope the startup probe tries (tables_db, users, teams, …). Run the same command in a terminal to see the real error:

APPWRITE_PROJECT_ID=<YOUR_PROJECT_ID> \
APPWRITE_API_KEY=<YOUR_API_KEY> \
APPWRITE_ENDPOINT=http://localhost:9501/v1 \
uvx mcp-server-appwrite

For a local Docker Appwrite instance the endpoint is typically http://localhost:9501/v1 (HTTP, not HTTPS). The value must be the API base (…/v1), not the Console URL.

Project environments

On Appwrite Cloud, a project can have environments (for example staging). To point a local server at one, keep APPWRITE_PROJECT_ID set to the ID of the project it belongs to and add the environment's ID:

APPWRITE_PROJECT_ID=<YOUR_PROJECT_ID> \
APPWRITE_ENVIRONMENT_ID=staging \
APPWRITE_API_KEY=<YOUR_API_KEY> \
uvx mcp-server-appwrite

Every request then carries X-Appwrite-Environment: staging next to the project's ID. The environment is fixed for the server's lifetime: a tool call that names another environment_id is refused rather than run in this one. Run one server per environment you want the agent to reach.

Reasons on writes

Every write the agent makes through appwrite_call_write_tool carries a one-line reason, which Appwrite records on the project's audit log (X-Appwrite-Reason). Self-hosted Appwrite versions that predate the header ignore it.

Connect your client

Claude Code 
claude mcp add appwrite \
  --env APPWRITE_PROJECT_ID=<YOUR_PROJECT_ID> \
  --env APPWRITE_API_KEY=<YOUR_API_KEY> \
  --env APPWRITE_ENDPOINT=https://<YOUR_APPWRITE_DOMAIN>/v1 \
  -- uvx mcp-server-appwrite
Claude Desktop

Edit your config via Settings → Developer → Edit Config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows), then fully restart the app.

{
  "mcpServers": {
    "appwrite": {
      "command": "uvx",
      "args": ["mcp-server-appwrite"],
      "env": {
        "APPWRITE_PROJECT_ID": "<YOUR_PROJECT_ID>",
        "APPWRITE_API_KEY": "<YOUR_API_KEY>",
        "APPWRITE_ENDPOINT": "https://<YOUR_APPWRITE_DOMAIN>/v1"
      }
    }
  }
}
Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).

{
  "mcpServers": {
    "appwrite": {
      "command": "uvx",
      "args": ["mcp-server-appwrite"],
      "env": {
        "APPWRITE_PROJECT_ID": "<YOUR_PROJECT_ID>",
        "APPWRITE_API_KEY": "<YOUR_API_KEY>",
        "APPWRITE_ENDPOINT": "https://<YOUR_APPWRITE_DOMAIN>/v1"
      }
    }
  }
}
VS Code (GitHub Copilot)

Edit .vscode/mcp.json (workspace) or your user configuration via the Command Palette → MCP: Open User Configuration.

{
  "servers": {
    "appwrite": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-appwrite"],
      "env": {
        "APPWRITE_PROJECT_ID": "<YOUR_PROJECT_ID>",
        "APPWRITE_API_KEY": "<YOUR_API_KEY>",
        "APPWRITE_ENDPOINT": "https://<YOUR_APPWRITE_DOMAIN>/v1"
      }
    }
  }
}
Codex

Edit ~/.codex/config.toml.

[mcp_servers.appwrite]
command = "uvx"
args = ["mcp-server-appwrite"]

[mcp_servers.appwrite.env]
APPWRITE_PROJECT_ID = "<YOUR_PROJECT_ID>"
APPWRITE_API_KEY = "<YOUR_API_KEY>"
APPWRITE_ENDPOINT = "https://<YOUR_APPWRITE_DOMAIN>/v1"
OpenCode

Edit opencode.json (project) or ~/.config/opencode/opencode.json (global).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "appwrite": {
      "type": "local",
      "command": ["uvx", "mcp-server-appwrite"],
      "enabled": true,
      "environment": {
        "APPWRITE_PROJECT_ID": "<YOUR_PROJECT_ID>",
        "APPWRITE_API_KEY": "<YOUR_API_KEY>",
        "APPWRITE_ENDPOINT": "https://<YOUR_APPWRITE_DOMAIN>/v1"
      }
    }
  }
}
Windsurf

Edit ~/.codeium/windsurf/mcp_config.json.

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