Claude CodeのAppwriteプラグインでFunctionsとSitesをデプロイする

Appwriteプラグインは、Claude CodeにAppwrite向けのSDK skill、ホスト型のMCPサーバー、そして/appwrite:deploy-functionと/appwrite:deploy-siteの2つのデプロイコマンドを足します。デプロイの実体はAppwrite CLIのappwrite pushで、コマンドは手順書として働きます。この記事は、プラグインに何が入るか、導入と認証、FunctionsとSitesを出す流れ、そして--forceや--with-variablesで事故を避ける設定を順に扱います。

Appwriteプラグインに入っているもの

プラグインは3種類の部品でできています。

skillはタスクに合えばClaudeが自動で読み込み、/appwrite:typescriptのように名前で直接呼ぶこともできます。コマンド名のappwrite:は、プラグイン内のskillが/プラグイン名:skill名の形で名前空間を持つ仕組みによるものです。

デプロイに関わるのはcliskillと2つのコマンドです。cliskillの説明文は、appwrite.config.jsonとappwrite clientの使い分け、pull / pushの流れ、CI向けの認証、関数とサイトの変数を扱うと書いています。コマンドを網羅する代わりにappwrite <command> --helpを読む方針で、フラグを推測させない作りです。

導入とMCPの認証

公式マーケットプレイスに載っているので、シェルから次のように入れます。

claude plugin install appwrite@claude-plugins-official

セッション内なら/plugin install appwrite@claude-plugins-officialです。見つからないときは、プラグインのリポジトリをマーケットプレイスとして足してから入れます。

claude plugin marketplace add appwrite/claude-plugin
claude plugin install appwrite@appwrite

開いたままのセッションには/reload-pluginsで反映します。そのうえでMCPの認証を済ませます。/mcpでappwriteサーバーを選んでAuthenticateを押すとブラウザーが開き、Appwriteのアカウントで許可します。APIキーやプロジェクトIDを手で設定する必要はありません。シェルからなら次のコマンドです。

claude mcp login plugin:appwrite:appwrite
claude mcp get plugin:appwrite:appwrite

2行目は認証と接続の状態を確かめるコマンドです。プラグイン同梱のMCPサーバーはplugin:<プラグイン名>:<サーバー名>の名前で登録されるため、ログインにもこの名前を使います。

注意点が2つあります。

• プラグインを入れたうえで、同じサーバーをclaude mcp addで手動登録しないでください。Appwriteのドキュメントは、二重に登録されると書いています
• 古い版のプラグインはエンドポイント・プロジェクトID・APIキーを尋ねる作りでした。そのとき入れたままなら、/pluginsのInstalledタブからプラグインを更新します

同梱MCPの仕組み自体はプラグイン同梱のMCPサーバーで扱っています。

デプロイコマンドは手動専用で、認証は別

2つのコマンドのフロントマターにはdisable-model-invocation: trueがあります。この指定があると、Claudeは自動でそのskillを読み込みません。公式のskill解説も、/deployのように副作用があり実行時期を自分で決めたいものに使う指定だと説明しています。「コードが仕上がったようだから」とClaudeが判断してデプロイを始めることは、コマンドの経路では起きません。

もう1つ見落としやすい点があります。MCPのOAuth認証と、デプロイに使うCLIの認証は別物です。コマンドの前提条件には次の3つが並びます。

1. Appwrite CLIをインストールしてある(npm install -g appwrite-cli)
2. appwrite loginで認証してある
3. appwrite initでプロジェクトを初期化してある

MCPでAuthenticateを済ませても、CLI側のログインは終わりません。プラグインの説明文は、この2つの認証が連動するとは書いていません。コマンドを呼ぶ前に、appwrite loginを別に済ませる流れで考えると、途中で止まりません。

Functionsをデプロイする

/appwrite:deploy-functionが案内する流れは、初期化・同期・設定・デプロイの4段です。

設定ファイルの例は次の形です。値はコマンドが示す例で、自分のプロジェクトのものではありません。

{
  "projectId": "<PROJECT_ID>",
  "endpoint": "https://<REGION>.cloud.appwrite.io/v1",
  "functions": [
    {
      "$id": "<FUNCTION_ID>",
      "name": "userAuth",
      "runtime": "node-18.0",
      "entrypoint": "userAuth.js",
      "commands": "npm install",
      "timeout": 15,
      "path": "functions/userAuth"
    }
  ]
}

例のランタイムはnode-18.0ですが、使えるランタイムの一覧はappwrite functions list-runtimesで取れます。例の値をそのまま写さず、一覧と照らしてください。ローカルでの動作確認にはappwrite run functionsが使えます。ファイルの変更を監視して再ビルドするローカルサーバーが立ちます。

Claudeへの頼み方は短くて済みます。

/appwrite:deploy-function userAuthをこのプロジェクトのFunctionsにデプロイして。
実行前に appwrite.config.json の差分を見せて

2行目の依頼は、公式の例ではなく設定の確認を挟むための書き方の一例です。

Sitesをデプロイする

/appwrite:deploy-siteも同じ4段で、対象がsitesに変わります。appwrite init sites、appwrite pull sites、設定の確認、appwrite push sitesの順です。

設定のキーは関数と違い、ビルド側の項目が中心です。コマンドが示す例では、framework、installCommand、buildCommand、outputDirectory、buildRuntime、adapter、specification、fallbackFileが並びます。

使えるフレームワークと仕様の一覧は、それぞれappwrite sites list-frameworksとappwrite sites list-specificationsで取れます。環境変数は、ビルド時と実行時(SSR)の両方で環境変数として読めると書かれています。

CIや非対話で動かすときの罠

CIでは先にヘッドレスの認証を済ませます。コマンドは、エンドポイント・プロジェクトID・APIキーを渡す形を示しています。

appwrite client \
  --endpoint https://<REGION>.cloud.appwrite.io/v1 \
  --project-id <PROJECT_ID> \
  --key <API_KEY>
 
appwrite push functions --function-id <FUNCTION_ID> --force

--forceは確認プロンプトを飛ばすフラグです。cliskillによれば、エージェントやCIは端末を持たないので、確認が要るpushは--forceなしだと失敗します。skillの指示は「先に利用者に確認し、そのうえで--forceを付ける」です。このフラグでスキップしてはいけないものも書かれています。変更表のlocal列が空のまま差分が出ているとき、--forceで押し切ってはいけません。先にその項目をpullします。

cliskillには、ほかにも踏みやすい点が3つあります。

• push all --all --forceは、関数・テーブル・バケット・チームなど全リソースを送ります。deploy-functionコマンドにも例として載っていますが、skillはpush function --function-id apiのように範囲を絞るよう案内しています
• --activate=falseを付けると、デプロイしても本番のトラフィックは新しい版に切り替わりません。切り替え前に確かめたいときの選択肢です
• --asyncはビルドの完了を待たずに戻ります

コマンドとskillで書き方が割れている点

同じプラグインの中で、サブコマンドの綴りが揃っていません。deploy-functionコマンドはappwrite push functionsと複数形で書き、cliskillの例はappwrite push function --function-id apiと単数形で書いています。サイト側のコマンドもpush sitesです。

どちらが受け付けられるのかは、プラグインの文書からは判断できません。手元のCLIでappwrite push --helpを見て、そのバージョンの綴りに合わせるのが確実です。Claudeに任せるときも「appwrite push --helpを読んでから実行して」と一言添えると、綴りの食い違いで止まりにくくなります。cliskill自身が、フラグを推測せずヘルプを読む方針を取っています。

デプロイだけ人の承認に残す

コマンドは手動専用ですが、Claudeは普段のBash実行の経路でもappwrite pushを呼べます。cliskillが自動で読み込まれたあとに「デプロイして」と頼めば、コマンドを経由せずにappwriteが走ります。確認を挟みたいなら、権限ルールのaskでpushだけを止めます。

{
  "permissions": {
    "ask": [
      "Bash(appwrite push *)"
    ]
  }
}

Bash(git push *)と同じ書き方で、appwrite pushで始まるコマンドは毎回確認が出ます。ワイルドカードの照合には限界があり、git -C . pushのようにオプションを挟んだ形は一致しない例が公式に載っています。appwriteでも同じ性質を前提に、CIで走る場合は別の層で守る構成になります。権限ルールの考え方はaws-serverlessプラグインの権限設定でも同じ型の例を扱っています。

つまずきやすい点

• コマンドが/appwrite:deploy-functionの形でしか出てこない。プラグインを入れた直後の既存セッションでは、/reload-pluginsを実行するまで一覧に出ません
• MCPのツールが「認証が必要」と出る。/mcpのRe-authenticateかclaude mcp login plugin:appwrite:appwriteでやり直します
• ブラウザーが開かない環境では、Claude Codeが表示するURLを別の端末で開きます
• MCPが使える状態でも、appwrite pushは別にappwrite loginが要ります
• Appwrite Cloudのリージョンごとのエンドポイントは、initやclient --project-idが設定ファイルに書き込みます。appwrite whoamiに出るアカウント用のホストと、プロジェクト用のリージョンホストは別物です

まとめ

Appwriteプラグインでデプロイの判断が人に残るのは、コマンドが手動専用だからです。その代わりBash経由のappwrite pushは塞がれていないので、本番を出すプロジェクトではaskルールと--activate=falseを組み合わせる構成が現実的です。プラグイン全般の入れ方と管理はClaude Codeのプラグインとマーケットプレイスにまとめています。