fly-io

Fly.io MCP サーバー

Fly.io のマシンとアプリケーションを管理する MCP サーバーです。このサーバーは、Fly.io のアプリとマシン（VM）に対する CRUD 操作を実行するツールを提供します。

主な機能

• MCP 経由で Fly.io のアプリケーションとマシンを管理
• アプリとマシンに対する完全な CRUD 操作
• マシンの起動、停止、再起動、一時停止
• デバッグ用のマシンイベントログの取得
• マシンの状態遷移を待機
• Docker イメージを Fly.io にデプロイ
• リージョンとマシンで絞り込んだアプリケーションログの取得
• 実行中のマシンでコマンドを実行
• Docker イメージの管理 — 現在のイメージの表示、リリースの一覧表示、新しいバージョンへの更新
• Fly.io レジストリへのイメージのプッシュ／プル — registry.fly.io と直接やり取り
• 権限ベースのアクセス制御に対応したツールのグループ化
• API 認証情報と CLI ツールを検証するヘルスチェック

機能

ツール

ツール名	権限	機能	説明
list_apps	readonly, write, admin	apps	Fly.io アプリケーションをすべて一覧表示
get_app	readonly, write, admin	apps	特定のアプリの詳細を取得
create_app	write, admin	apps	新しい Fly.io アプリケーションを作成
delete_app	admin	apps	アプリケーションを削除
list_machines	readonly, write, admin	machines	アプリ内のマシンをすべて一覧表示
get_machine	readonly, write, admin	machines	特定のマシンの詳細を取得
get_machine_events	readonly, write, admin	machines	マシンのイベントログを取得（デバッグ用）
create_machine	write, admin	machines	Docker イメージを使って新しいマシンを作成
update_machine	write, admin	machines	マシンの設定を更新
delete_machine	admin	machines	マシンを削除
start_machine	write, admin	machines	停止中のマシンを起動
stop_machine	write, admin	machines	実行中のマシンを停止
restart_machine	write, admin	machines	マシンを再起動（停止後に起動）
suspend_machine	write, admin	machines	マシンを一時停止（状態をディスクに保存）
wait_machine	write, admin	machines	マシンが指定の状態になるまで待機
get_logs	readonly, write, admin	logs	アプリケーションログを取得
machine_exec	write, admin	ssh	マシン上でコマンドを実行
show_image	readonly, write, admin	images	現在の Docker イメージの詳細を表示
list_releases	readonly, write, admin	images	イメージ参照を含むリリースを一覧表示
update_image	write, admin	images	アプリのイメージを最新版または指定版に更新
push_new_fly_registry_image	write, admin	registry	ローカルイメージを Fly.io レジストリにプッシュ
pull_fly_registry_image	readonly, write, admin	registry	Fly.io レジストリからイメージをプル
check_fly_registry_image	readonly, write, admin	registry	レジストリにイメージが存在するか確認

セキュリティに関する考慮事項

machine_exec ツールを使うと、Fly.io マシン上で任意のコマンドを実行できます。強力な機能であるため、慎重に使用してください。

• ENABLED_TOOLGROUPS="readonly" または ENABLED_TOOLGROUPS="readonly,write" を設定して、machine_exec を含む管理ツールを無効にすることを検討してください
• このサーバーの実行には fly CLI が必要です。つまり、シェルコマンドを実行できます
• すべての操作は FLY_IO_API_TOKEN を使って認証されます

ツールグループ

ENABLED_TOOLGROUPS 環境変数を使って、利用可能なツールを制御します。次の 2 種類のグループに対応しており、組み合わせて指定できます。

権限グループ（許可する操作）

グループ	説明
readonly	読み取り専用の操作（一覧表示、取得）
write	書き込み操作（作成、更新、起動、停止）
admin	管理操作（アプリ／マシンの削除）

機能グループ（有効にする機能）

グループ	説明
apps	アプリ管理ツール（list_apps、get_app、create_app、delete_app）
machines	マシン管理ツール（一覧表示、取得、作成、更新、削除、起動、停止）
logs	ログ取得ツール（get_logs）
ssh	リモート実行ツール（machine_exec）
images	イメージ管理ツール（show_image、list_releases、update_image）
registry	Docker レジストリツール（push_new_fly_registry_image、pull_fly_registry_image、check_fly_registry_image） - Docker CLI が必要

例：

• ENABLED_TOOLGROUPS="readonly" - 読み取り操作のみ（すべての機能）
• ENABLED_TOOLGROUPS="readonly,write" - 読み取りと書き込みを許可し、削除は不可（すべての機能）
• ENABLED_TOOLGROUPS="machines,logs" - すべての権限を許可し、マシンとログの機能のみ
• ENABLED_TOOLGROUPS="readonly,machines" - マシンへの読み取り専用アクセスのみ
• 未設定 - すべてのツールを有効化（デフォルト）

アプリのスコープ設定

FLY_IO_APP_NAME を設定すると、サーバーは「スコープモード」で動作します。

• アプリ管理ツールは無効になります：list_apps、get_app、create_app、delete_app は利用できません
• マシンツールは制限されます：すべてのマシン操作は、設定されたアプリに対してのみ実行できます
• app_name は省略可能になります：マシンツールでは、スコープが設定されたアプリが自動的に使用されます
• アプリをまたぐ操作はブロックされます：別のアプリに対する操作を試みると、エラーが返されます

次のような用途に便利です。

• 1 つのアプリケーションへのアクセスを制限する
• ツールの使用を簡素化する（app_name を指定する必要がありません）
• 誤ったアプリに対する操作を防ぐ

クイックスタート

前提条件

1. Fly.io アカウント - fly.io で登録
2. Fly.io API トークン - こちらから作成
3. Fly.io CLI（fly）をインストール済み - インストール手順
4. Docker CLI をインストール済み（任意） - レジストリツール（push_image、pull_image、check_registry_image）に必要です
5. Node.js 18 以降をインストール済み

設定

環境変数

変数	必須	説明	デフォルト
FLY_IO_API_TOKEN	はい	Fly.io 認証用の API トークン	-
FLY_IO_APP_NAME	いいえ	サーバーの対象を単一のアプリに限定します（アプリ管理を無効化）	-
ENABLED_TOOLGROUPS	いいえ	有効にするツールグループをカンマ区切りで指定します	すべて有効
SKIP_HEALTH_CHECKS	いいえ	起動時の API 検証をスキップします	false
DISABLE_DOCKER_CLI_TOOLS	いいえ	Docker ベースのレジストリツールを無効にします	false

Claude Desktop の設定

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fly-io": {
      "command": "npx",
      "args": ["-y", "fly-io-mcp-server"],
      "env": {
        "FLY_IO_API_TOKEN": "fo_your_token_here"
      }
    }
  }
}

アプリのスコープを指定する場合（単一のアプリに制限します）：

{
  "mcpServers": {
    "fly-io": {
      "command": "npx",
      "args": ["-y", "fly-io-mcp-server"],
      "env": {
        "FLY_IO_API_TOKEN": "fo_your_token_here",
        "FLY_IO_APP_NAME": "my-production-app"
      }
    }
  }
}

Claude Desktop を再起動すれば、準備完了です！

使用例

すべてのアプリを一覧表示する

Use the list_apps tool to see all my Fly.io applications.

新しいアプリを作成してマシンをデプロイする

Create a new Fly.io app called "my-web-app" in my personal organization,
then deploy an nginx container to it with 512MB of RAM.

マシンをスケーリングする

List the machines in my-web-app and create two more copies
in different regions (lax and lhr).

デプロイを更新する

Update all machines in my-web-app to use the nginx:1.25 image.

クラッシュしたマシンをデバッグする

Get the events for machine abc123 in my-web-app to see why it crashed.

応答しなくなったマシンを再起動する

Restart machine abc123 in my-web-app to clear its state.

アプリケーションのログを表示する

Get the logs for my-web-app to see what's happening.

マシンでコマンドを実行する

Run "ls -la /app" on machine abc123 in my-web-app to see the app files.

現在のイメージバージョンを確認する

Show me the current Docker image details for my-web-app.

デプロイ履歴を一覧表示する

List the last 5 releases for my-web-app to see the deployment history.

新しいイメージに更新する

Update my-web-app to use the latest image version.

ローカルイメージを Fly.io レジストリにプッシュする

Push my local "my-app:v2" image to the Fly.io registry for my-web-app with tag "v2".

レジストリにイメージが存在するか確認する

Check if the image with tag "v2" exists in the Fly.io registry for my-web-app.

開発

セットアップ

# Clone the repository
git clone https://github.com/pulsemcp/mcp-servers.git
cd mcp-servers/experimental/fly-io

# Install dependencies
npm run install-all

# Build
npm run build

開発モードで実行する

npm run dev

テスト

# Run functional tests in watch mode
npm test

# Run tests once
npm run test:run

# Run integration tests
npm run test:integration

# Run manual tests (requires .env with API token)
npm run test:manual:setup  # First time only
npm run test:manual

リントとフォーマット

# Check for linting issues (run from repo root)
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code
npm run format

アーキテクチャ

このサーバーは、REST API を直接使用せず、すべての操作に Fly.io CLI（fly） を使用します。この方式には次の利点があります。

• すべてのツールで一貫した動作を実現します
• ログやコマンド実行など、CLI 専用の機能を利用できます
• 認証を簡素化します（FLY_API_TOKEN 環境変数を使用します）

レート制限

Fly.io API にはレート制限があり、CLI によって適用されます。

• 一般：アクションごとに毎秒 1 リクエスト（バースト時：毎秒 3 リクエスト）
• マシンの取得：毎秒 5 リクエスト（バースト時：毎秒 10 リクエスト）
• アプリの削除：毎分 100 回

プロジェクト構成

fly-io/
├── local/                 # Local server implementation
│   ├── src/
│   │   ├── index.ts      # Main entry point
│   │   └── index.integration-with-mock.ts
│   └── package.json
├── shared/               # Shared business logic
│   ├── src/
│   │   ├── server.ts     # Server factory
│   │   ├── tools.ts      # Tool registration
│   │   ├── tools/        # Individual tool implementations
│   │   ├── fly-io-client/  # Fly.io CLI client
│   │   │   ├── fly-cli-client.ts   # CLI wrapper
│   │   │   └── fly-io-client.ts    # Interface & exports
│   │   ├── logging.ts
│   │   └── types.ts
│   └── package.json
├── tests/
│   ├── functional/       # Unit tests with mocks
│   ├── integration/      # MCP protocol tests
│   ├── manual/          # Real API tests
│   └── mocks/
├── scripts/
├── package.json
└── README.md

ライセンス

MIT