trackmcp
Back to directory
brannn

fly-mcp

View on GitHub

MCP server for managing your Fly.io infrastructure

0 stars GoServers & Infrastructure Updated Jun 7, 2025

Documentation

fly-mcp

An open-source MCP (Model Context Protocol) server for Fly.io infrastructure management, enabling AI-driven DevOps workflows through natural language interactions.

🚀 Quick Start

Prerequisites

  • Go 1.21 or later
  • Fly.io account and API token
  • Git

Local Development Setup

1. Clone the repository

bash
git clone https://github.com/brannn/fly-mcp.git
   cd fly-mcp

2. Set up environment variables

bash
export FLY_MCP_FLY_API_TOKEN="your_fly_api_token_here"
   export FLY_MCP_FLY_ORGANIZATION="your_fly_org_here"

3. Build and run

bash
make build
   make run

Or for development with hot reload:

bash
make dev

Production Deployment on Fly.io

Deploy using Fly.io's MCP infrastructure:

bash
fly mcp launch \
  "github.com/brannn/fly-mcp" \
  --claude --cursor --zed \
  --server fly-infrastructure \
  --secret FLY_API_TOKEN=fo1_your_token \
  --secret FLY_ORG=your-org-name

🏗️ Architecture

Project Structure

code
fly-mcp/
├── cmd/fly-mcp/              # Main application entry point
├── pkg/
│   ├── mcp/                  # MCP protocol implementation
│   ├── fly/                  # Fly.io API client (coming soon)
│   ├── auth/                 # Authentication (coming soon)
│   ├── tools/                # MCP tool implementations (coming soon)
│   └── config/               # Configuration management
├── internal/
│   ├── server/               # HTTP server implementation
│   ├── security/             # Security utilities (coming soon)
│   └── logger/               # Structured logging
├── config.local.yaml         # Local development configuration
├── config.production.yaml    # Production configuration
└── Makefile                  # Build automation

Configuration

The application supports flexible configuration through:

  • YAML files: `config.local.yaml` for development, `config.production.yaml` for production
  • Environment variables: All config values can be overridden with `FLY_MCP_` prefixed env vars
  • Command line flags: `--config` and `--log-level` flags

Environment Variables

VariableDescriptionRequired
`FLY_MCP_FLY_API_TOKEN`Fly.io API tokenYes
`FLY_MCP_FLY_ORGANIZATION`Fly.io organization nameYes
`FLY_MCP_ENVIRONMENT`Environment (local/production)No
`FLY_MCP_LOGGING_LEVEL`Log level (debug/info/warn/error)No

🛠️ Development

Available Make Targets

bash
make build          # Build the binary
make build-all      # Build for all platforms
make test           # Run tests
make test-coverage  # Run tests with coverage
make lint           # Run linters
make fmt            # Format code
make clean          # Clean build artifacts
make dev            # Run in development mode
make validate-config # Validate configuration
make docker-build   # Build Docker image
make help           # Show all available targets

Running Tests

bash
# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run benchmarks
make benchmark

Code Quality

bash
# Format code
make fmt

# Run linters
make lint

# Run all checks
make check

🔧 Configuration Examples

Local Development

Create a `.env` file or set environment variables:

bash
export FLY_MCP_FLY_API_TOKEN="fo1_your_development_token"
export FLY_MCP_FLY_ORGANIZATION="your-dev-org"
export FLY_MCP_LOGGING_LEVEL="debug"

Production on Fly.io

Set secrets in your Fly.io app:

bash
fly secrets set FLY_API_TOKEN=fo1_your_production_token
fly secrets set FLY_ORG=your-production-org

🛠️ Available MCP Tools

Core Tools

ToolDescriptionExample Usage
`ping`Test connectivity and server response`{"name": "ping", "arguments": {"message": "Hello!"}}`

Fly.io Management Tools

ToolDescriptionExample Usage
`fly_list_apps`List all applications with filtering`{"name": "fly_list_apps", "arguments": {"status_filter": "running"}}`
`fly_app_info`Get detailed application information`{"name": "fly_app_info", "arguments": {"app_name": "my-app"}}`
`fly_status`Real-time application and machine status`{"name": "fly_status", "arguments": {"app_name": "my-app"}}`
`fly_restart`Restart applications with confirmation`{"name": "fly_restart", "arguments": {"app_name": "my-app", "confirm": true}}`
`fly_scale`Scaling status and recommendations`{"name": "fly_scale", "arguments": {"app_name": "my-app", "action": "status"}}`

Tool Features

  • 🔒 Security: All tools require proper authentication and permissions
  • 📝 Audit Logging: All operations are logged for compliance and debugging
  • ⚡ Real-time: Status and machine information is fetched in real-time
  • 🛡️ Safety: Destructive operations require explicit confirmation
  • 📊 Rich Output: Human-readable responses with actionable recommendations

🧪 Testing the MCP Server

Automated Testing

Use the provided test script to verify all tools:

bash
# Start the server first
make dev

# In another terminal, run tests
./scripts/test-mcp-tools.sh

Manual Testing

1. Health Check

bash
curl http://localhost:8080/health

2. MCP Initialize

bash
curl -X POST http://localhost:8080/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "initialize",
       "params": {
         "protocolVersion": "2024-11-05",
         "capabilities": {},
         "clientInfo": {"name": "test-client", "version": "1.0.0"}
       }
     }'

3. List Available Tools

bash
curl -X POST http://localhost:8080/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 2,
       "method": "tools/list"
     }'

4. Test Ping Tool

bash
curl -X POST http://localhost:8080/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 3,
       "method": "tools/call",
       "params": {
         "name": "ping",
         "arguments": {"message": "Hello from fly-mcp!"}
       }
     }'

5. Test Fly.io Tools (requires valid credentials)

bash
curl -X POST http://localhost:8080/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 4,
       "method": "tools/call",
       "params": {
         "name": "fly_list_apps",
         "arguments": {}
       }
     }'

🎯 Current Status

Phase 2 Complete: Fly.io API Integration & Core Tools

✅ Implemented Features

  • ✅ Project structure and build system
  • ✅ Configuration management (local/production environments)
  • ✅ HTTP server with middleware (CORS, rate limiting, logging)
  • ✅ MCP protocol handler with full request/response handling
  • ✅ Structured logging with audit trails and security events
  • ✅ Fly.io API integration (hybrid approach: fly-go + Machines API)
  • ✅ Authentication & authorization with permissions and audit logging
  • ✅ Core MCP tools:
    • `ping` - Test tool for connectivity
    • `fly_list_apps` - List all applications with filtering
    • `fly_app_info` - Get detailed application information
    • `fly_status` - Real-time application and machine status
    • `fly_restart` - Restart applications with confirmation
    • `fly_scale` - Scaling status and recommendations
  • ✅ Health checks and metrics endpoints
  • ✅ Comprehensive error handling and validation
  • ✅ Security features (rate limiting, CORS, audit logging)

🔄 Coming Next (Phase 3)

  • 🔄 Additional tools: logs, secrets, volumes, certificates
  • 🔄 Deploy tool for application deployment
  • 🔄 Advanced scaling with auto-scaling recommendations
  • 🔄 Monitoring integration with alerts and dashboards
  • 🔄 CI/CD pipeline and automated testing
  • 🔄 Documentation and usage examples

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📞 Support

Frequently asked questions

What is fly-mcp?

fly-mcp is MCP server for managing your Fly.io infrastructure

How do I install fly-mcp?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is fly-mcp open source?

Yes — it is hosted on GitHub at https://github.com/brannn/fly-mcp.

Related MCP tools

grafanamcp-grafana

MCP server for Grafana Go-based implementation. Trusted by 1700+ developers. Trusted by 1700+ developers. Trusted by 1700+ developers.

1,725 Go
controlplaneio-fluxcdflux-operator

Flux Operator is a Kubernetes controller for managing the lifecycle of Flux CD for the Model Context Protocol. Enhance AI assistants with powerful integrations.

375 Go
continuous-deliveryfluxcdgitops+1
strowkmcp-k8s-go

MCP server connecting to Kubernetes Go-based implementation.

351 Go
kubernetesmcpserver
TheLunarCompanylunar

Lunar.dev: Ground Control for 3rd Party APIs for the Model Context Protocol. Enhance AI assistants with powerful integrations. Go-based implementation.

305 Go
apiapi-consumerapi-consumption+12
mudlerlocalai

:robot: The free, Open Source alternative to OpenAI, Claude and others. Self-hosted and local-first. Drop-in replacement for OpenAI, running on consumer-gra...

36,790 Go
aiapiaudio-generation+17
googleapisgenai-toolbox

MCP Toolbox for Databases is an open source MCP server for databases. Go-based implementation. Trusted by 10900+ developers.

10,995 Go
databasesgenaillms+1

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP