willibrandon/openttd-mcp

OpenTTD MCP Server

Model Context Protocol server for OpenTTD, enabling AI assistants to play OpenTTD via the Admin Port.

Features

• Complete Admin Port Implementation: Full binary protocol support for OpenTTD communication
• 25+ MCP Tools: Comprehensive game control including construction, vehicles, and economics
• Intelligent Analysis: Route finding, profit calculation, and network optimization
• Real-time State Tracking: Synchronized game state with companies, towns, industries, and vehicles
• Financial Management: Budget control, loan management, and financial forecasting
• Automated Operations: Vehicle orders, infrastructure building, and market analysis

Quick Start

Prerequisites

• Go 1.21 or higher
• Docker and Docker Compose
• OpenTTD server with Admin Port enabled

Installation

# Clone the repository
git clone https://github.com/willibrandon/openttd-mcp
cd openttd-mcp

# Install dependencies
go mod download

# Build the MCP server
go build -o bin/openttd-mcp main.go

Running the Server

# Start OpenTTD server with Docker
docker-compose up openttd -d

# Run MCP server
./bin/openttd-mcp

# Or with environment variables
OPENTTD_HOST=localhost OPENTTD_PORT=3977 OPENTTD_ADMIN_PASSWORD=admin123 ./bin/openttd-mcp

Docker Compose (All-in-One)

# Start both OpenTTD and MCP server
docker-compose up

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Configuration

Environment Variables

Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "openttd": {
      "command": "/path/to/openttd-mcp",
      "env": {
        "OPENTTD_HOST": "localhost",
        "OPENTTD_PORT": "3977",
        "OPENTTD_ADMIN_PASSWORD": "admin123"
      }
    }
  }
}

Available Tools

Connection Management

• connect_to_server - Connect to OpenTTD server
• disconnect - Disconnect from server
• server_status - Get connection status

Information Tools

• get_server_info - Server details and map information
• list_companies - All companies with statistics
• list_towns - Towns with population data
• list_industries - Industries and production
• list_vehicles - Vehicle fleet information
• get_map_info - Map size and landscape
• execute_command - Run console commands

Construction Tools

• build_depot - Build vehicle depots
• build_station - Build stations
• build_road - Build road segments
• build_vehicle - Purchase vehicles

Vehicle Management

• manage_orders - Set vehicle orders
• start_stop_vehicle - Control vehicle operation
• sell_vehicle - Sell vehicles

Economic Tools

• get_finances - Company financial data
• company_analysis - Performance analysis
• set_company_budget - Budget management
• manage_loan - Loan operations
• financial_forecast - Revenue projections

Advanced Analysis

• find_profitable_routes - Identify high-profit routes
• analyze_industry_chains - Industry connections
• calculate_route_profit - Route profitability
• network_optimizer - Network efficiency
• market_analysis - Competitive analysis

Testing

# Run all tests
go test ./...

# Run integration tests (requires OpenTTD server)
go test -v ./test/integration/...

# Run benchmarks
go test -bench=. ./test/integration/...

# Generate coverage report
go test -cover ./...

License

MIT

Contributing

Contributions are welcome! Please ensure:

• All tests pass (go test ./...)
• Code follows Go conventions (go fmt ./...)
• New features include tests
• Documentation is updated