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，这意味着它可以执行 shell 命令
• 所有操作均通过你的 FLY_IO_API_TOKEN 进行身份验证

工具组

通过 ENABLED_TOOLGROUPS 环境变量控制可用的工具。支持两种类型的组，且可以组合使用：

权限组（允许执行哪些操作）

组	描述
readonly	只读操作（list、get）
write	写入操作（create、update、start、stop）
admin	管理操作（删除应用／机器）

功能组（启用哪些功能）

组	描述
apps	应用管理工具（list_apps、get_app、create_app、delete_app）
machines	机器管理工具（list、get、create、update、delete、start、stop）
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 将变为可选项：机器工具会自动使用范围限定的应用
• 跨应用操作将被阻止：尝试对其他应用进行操作时会返回错误

适用于以下场景：

• 将访问权限限制在单个应用
• 简化工具使用（无需指定 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

架构

此服务使用 Fly.io CLI（fly） 执行所有操作，而非直接使用 REST API。此方案：

• 确保所有工具的行为一致
• 支持日志和命令执行等仅限 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