Claude Code・Codex・Cursor から hanamii に公開する

AI コーディングエージェントに「hanamii にデプロイして」と頼むだけで公開できるようにする手順。スキルの入れ方、API トークンの発行、エージェントが実行する流れ、公式 CLI（npx -y hanamii deploy）と MCP サーバーの使い方、人が curl だけで公開する手順も載せています。

エージェントに「hanamii にデプロイして」と頼めるようにするには？

Claude Code・Codex・Cursor などの AI コーディングエージェントに、hanamii への公開手順を教えておく仕組みがあります。一度入れておけば、作ったアプリを「hanamii にデプロイして」「日本国内のサーバーで公開して」と頼むだけで、ZIP の作成からアップロード、検証、公開、URL の確認までをエージェントが進めます。仕組みは Agent Skills（エージェントが読む手順ファイル）と公式 CLI（npm パッケージ hanamii）で、どちらも公開 API を使います。CLI は MCP サーバーも兼ねるので、Claude Code・Cursor・Codex・Claude Desktop にツールとして登録することもできます（2026年10月時点）。

1. スキルを入れる

作業中のプロジェクトのディレクトリで次を実行します。

npx skills add hanamii-sakura/hanamii-skills

どのエージェントに入れるかを聞かれるので、使っているものを選びます。Claude Code なら .claude/skills/、Codex と Cursor なら .agents/skills/ に hanamii-deploy が入ります。全部のエージェントの共通設定に入れるなら -g -y を付けます。

スキルの中身は GitHub の hanamii-sakura/hanamii-skills で読めます。

2. API トークンを発行する

hanamii にログインし、サイドバーのワークスペース設定 → APIトークンを開く（トークンは今開いているワークスペースに対して発行されます）
トークンを発行する（hnm_ で始まります。表示は一度だけなので控えておく）
CLI に保存するか、作業中のシェルに設定する

npx -y hanamii login          # 貼り付けて保存（~/.config/hanamii/config.json）
# または
export HANAMII_TOKEN=hnm_...

トークンはエージェントとの会話やファイルに貼らず、hanamii login か環境変数で渡します。

3. エージェントに頼む

hanamii にデプロイして

エージェントはスキルの手順に沿って次を行います。

npx -y hanamii whoami でトークンを確認し、アプリが Node.js・Python・PHP のどれかを確認する
package.json の scripts.start や PORT の扱いなど、公開に必要な構成を整える
npx -y hanamii deploy --name <アプリ名> で ZIP を作り（node_modules や .env は除外）、アップロードして検証し、プロジェクトを作成または再デプロイする
公開が終わるまで待ち、URL を伝える
失敗したら、検証エラー・ビルド失敗・起動失敗のどれかを見分け、npx -y hanamii logs で原因を見て直す

成功するとプロジェクトのディレクトリに .hanamii/project.json が保存されるので、2 回目からは「hanamii に再デプロイして」だけで同じプロジェクトを更新します。環境変数の設定やログの確認も頼めます。

4. 公式 CLI を直接使う

エージェントを介さずに、人が同じ CLI を使うこともできます。Node.js 20.3 以上があれば、インストールせずに npx で動きます。

npx -y hanamii login                       # トークンを貼り付けて保存
npx -y hanamii deploy --name my-app        # 新規作成。完了まで待って URL を表示
npx -y hanamii deploy                      # 2 回目以降は .hanamii/project.json のリンク先に再デプロイ
npx -y hanamii env set API_KEY=... --restart
npx -y hanamii logs --since -15m

コマンドの一覧と --json 出力、終了コードは hanamii-sakura/hanamii-cli の README にあります。

MCP サーバーとして登録する

同じパッケージが MCP サーバーになります。登録するクライアントに合わせて設定を表示します。

npx -y hanamii mcp install --client claude-code     # cursor / codex / claude-desktop も可

Claude Code なら claude mcp add hanamii -- npx -y hanamii mcp で登録できます。登録後は deploy_project・get_logs・set_env・restart_project などのツールをエージェントが直接呼びます。プロジェクトの削除は既定で無効で、起動引数に --allow-delete を付けたときだけ有効になります。

5. 人が curl だけで公開する

CLI を使えない環境でも、同じ流れを curl で実行できます。詳しい仕様は公開 API 利用ガイドにあります。

export BASE_URL=https://hanamii.jp
export HANAMII_TOKEN=hnm_...

# ZIP を作る（不要物を除外）
zip -r app.zip . -x "node_modules/*" ".next/*" "dist/*" "build/*" ".git/*" ".env*"

# 1. アップロード URL を発行する
curl -s -X POST "$BASE_URL/api/v1/uploads" \
  -H "Authorization: Bearer $HANAMII_TOKEN" -H "Content-Type: application/json" \
  --data '{"workspaceId":"ws_xxx","fileName":"app.zip","contentType":"application/zip"}'
# → upload.id と upload.uploadUrl が返る

# 2. ZIP を置く
curl -X PUT '<upload.uploadUrl>' -H 'Content-Type: application/zip' --data-binary '@app.zip'

# 3. 検証して checkId を得る
curl -sS -N -X POST "$BASE_URL/api/v1/uploads/<upload.id>/check" \
  -H "Authorization: Bearer $HANAMII_TOKEN" -H "Content-Type: application/json" --data '{}'

# 4. プロジェクトを作って公開する
curl -N -X POST "$BASE_URL/api/v1/projects" \
  -H "Authorization: Bearer $HANAMII_TOKEN" -H "Content-Type: application/json" \
  --data '{"workspaceId":"ws_xxx","name":"my-app","source":{"type":"zip","checkId":"<result.checkId>"}}'

# 5. 完了を待って URL を読む
curl -s "$BASE_URL/api/v1/projects/<project.id>" -H "Authorization: Bearer $HANAMII_TOKEN"
# → latestDeployment.readyState が READY になったら project.url が公開 URL

ワークスペース ID は GET /api/v1/workspaces で分かります。checkId は使い捨てなので、再デプロイのたびに手順 1〜3 をやり直します。

よくある質問

GitHub 連携でも使えますか。 スキルは ZIP での公開を基本にしています。GitHub 連携を先に画面でつないでおけば、POST /api/v1/projects の source.type を git にして作成できます。日々の更新は push だけで済むので、継続開発なら GitHub 連携がおすすめです。

無料プランで使えますか。 使えます。無料プランで公開できるアプリは 1 本です。2 本目からは Light（月額 980 円）が必要です。

MCP サーバはありますか。 あります。npx -y hanamii mcp で起動する stdio サーバーで、上の「MCP サーバーとして登録する」の手順で Claude Code・Cursor・Codex・Claude Desktop に登録できます。