Fly Io

Fly.io MCP Server

MCP server for managing Fly.io machines and applications. This server provides tools for CRUD operations on Fly.io apps and machines (VMs).

Highlights

• Manage Fly.io applications and machines via MCP
• Full CRUD operations for apps and machines
• Start, stop, restart, and suspend machines
• Get machine event logs for debugging
• Wait for machine state transitions
• Deploy Docker images to Fly.io
• Retrieve application logs with region and machine filtering
• Execute commands on running machines
• Manage Docker images - view current image, list releases, update to new versions
• Push/pull images to Fly.io registry - interact with registry.fly.io directly
• Tool grouping for permission-based access control
• Health checks for API credential and CLI tool validation

Capabilities

Tools

Security Considerations

The machine_exec tool allows executing arbitrary commands on Fly.io machines. This is a powerful capability that should be used with caution:

• Consider using ENABLED_TOOLGROUPS="readonly" or ENABLED_TOOLGROUPS="readonly,write" to disable administrative tools including machine_exec
• The server requires the fly CLI to be installed, which means it has access to execute shell commands
• All operations are authenticated via your FLY_IO_API_TOKEN

Tool Groups

Control which tools are available via the ENABLED_TOOLGROUPS environment variable. Two types of groups are supported and can be combined:

Permission Groups (what operations are allowed)

Feature Groups (what features are enabled)

Examples:

• ENABLED_TOOLGROUPS="readonly" - Only read operations (all features)
• ENABLED_TOOLGROUPS="readonly,write" - Read and write, no delete (all features)
• ENABLED_TOOLGROUPS="machines,logs" - All permissions, only machines and logs features
• ENABLED_TOOLGROUPS="readonly,machines" - Read-only access to machines only
• Not set - All tools enabled (default)

App Scoping

When FLY_IO_APP_NAME is set, the server operates in "scoped mode":

• App management tools are disabled: list_apps, get_app, create_app, delete_app are not available
• Machine tools are restricted: All machine operations only work on the configured app
• app_name becomes optional: Machine tools will automatically use the scoped app
• Cross-app operations are blocked: Attempting to operate on a different app returns an error

This is useful for:

• Restricting access to a single application
• Simplifying tool usage (no need to specify app_name)
• Preventing accidental operations on wrong apps

Quick Start

Prerequisites

1. A Fly.io account - Sign up at fly.io
2. A Fly.io API token - Create one here
3. Fly.io CLI (`fly`) installed - Install instructions
4. Docker CLI installed (optional) - Required for registry tools (push_image, pull_image, check_registry_image)
5. Node.js 18+ installed

Configuration

Environment Variables

Claude Desktop Configuration

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" } } } }

With app scoping (restricts to a single app):

{

"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" } } } }

Restart Claude Desktop and you should be ready to go!

Usage Examples

List all apps

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

Create a new app and deploy a machine

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.

Scale machines

List the machines in my-web-app and create two more copies

in different regions (lax and lhr).

Update a deployment

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

Debug a crashed machine

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

Restart a stuck machine

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

View application logs

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

Execute a command on a machine

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

Check current image version

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

List deployment history

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

Update to a new image

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

Push a local image to Fly.io registry

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

Check if an image exists in the registry

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

Development

Setup

# 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

Running in Development Mode

npm run dev

Testing

# 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

Linting and Formatting

# Check for linting issues (run from repo root)

npm run lint

Auto-fix linting issues

npm run lint:fix

Format code

npm run format

Architecture

This server uses the Fly.io CLI (`fly`) for all operations instead of the REST API directly. This approach:

• Ensures consistent behavior across all tools
• Enables CLI-only features like logs and command execution
• Simplifies authentication (uses FLY_API_TOKEN environment variable)

Rate Limits

The Fly.io API enforces rate limiting (applied by the CLI):

• General: 1 request/second/action (burst: 3 req/s)
• Get Machine: 5 req/s (burst: 10 req/s)
• Delete App: 100/minute

Project Structure

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 # S