MCP Tilt Server

A Model Context Protocol (MCP) server that provides read-only access to Tilt.dev resources and logs. This package can be run as a CLI tool via npx and supports both Node.js native and Docker modes.

Installation

# Run directly with npx (recommended)
npx @gc-mcp/tilt --help

# Or install globally
npm install -g @gc-mcp/tilt
mcp-tilt --help

Quick Start

# Start the server in Node mode (default)
npx @gc-mcp/tilt

# Start on a specific port
npx @gc-mcp/tilt --port 9000

# Start in Docker mode
npx @gc-mcp/tilt --mode docker

# Set environment variables
npx @gc-mcp/tilt --env TILT_HOST=localhost --env LOG_LEVEL=debug

Usage

Command Line Interface

Usage: mcp-tilt [options]

MCP Server for Tilt.dev - provides read-only access to Tilt resources and logs

Options:
  -V, --version          output the version number
  -p, --port <port>      Port to listen on (default: 8087 or MCP_TILT_PORT env var)
  -e, --env <key=value>  Set environment variable (can be used multiple times)
  -m, --mode <mode>      Server mode: node or docker (default: node or MCP_TILT_MODE env var)
  --dry-run              Validate configuration without starting server
  --status               Check server status and exit
  -h, --help             output usage information

Server Modes

Node Mode (Default)

Runs the MCP server directly in Node.js. This is the fastest and most efficient mode.

npx @gc-mcp/tilt --mode node --port 8087

Docker Mode

Runs the MCP server in a Docker container. The CLI automatically handles container lifecycle management.

npx @gc-mcp/tilt --mode docker --port 8087

Note: Docker mode requires Docker to be installed and running.

Configuration

Environment Variables

You can set environment variables using the --env flag or by setting them in your environment:

# Via CLI flags
npx @gc-mcp/tilt --env TILT_HOST=localhost --env TILT_PORT=10350

# Via environment variables
export TILT_HOST=localhost
export TILT_PORT=10350
npx @gc-mcp/tilt

Available Environment Variables

• MCP_TILT_PORT: Default port for the server (default: 8087)
• MCP_TILT_MODE: Default server mode (default: node)
• TILT_HOST: Tilt API host (default: localhost)
• TILT_PORT: Tilt API port (default: 10350)
• TILT_USE_CLI: Use Tilt CLI instead of API (default: false)
• LOG_LEVEL: Logging level (default: info)
• LOG_MAX_LINES: Maximum log lines to retrieve (default: 1000)
• RESP_MAX_BYTES: Maximum response size in bytes (default: 1048576)
• STREAM_THROTTLE_MS: Stream throttling interval (default: 100)
• REDACTION_PATTERNS: Comma-separated patterns to redact from logs
• VERBOSE: Enable verbose logging (default: false)

Health Checks

The server provides a health check endpoint at /health:

curl http://localhost:8087/health

Response:

{
  "status": "healthy",
  "timestamp": "2025-01-24T12:00:00.000Z",
  "service": "mcp-tilt-server"
}

MCP Integration

Available Tools

The server provides the following MCP tools:

• check_tilt_status: Check if Tilt is running and accessible
• list_resources: List all Tilt resources
• get_status: Get status for a specific resource or all resources
• get_logs: Get logs for a specific resource
• tail_logs: Stream logs for a specific resource in real-time
• search_logs: Search logs for a specific resource

MCP Client Configuration

Configure your MCP client to connect to the server:

{
  "mcpServers": {
    "tilt": {
      "command": "npx",
      "args": ["@gc-mcp/tilt", "--port", "8087"],
      "env": {
        "TILT_HOST": "localhost",
        "TILT_PORT": "10350"
      }
    }
  }
}

For HTTP mode (when using Docker or HTTP clients):

{
  "mcpServers": {
    "tilt": {
      "url": "http://localhost:8087/mcp"
    }
  }
}

Troubleshooting

Common Issues

Port Already in Use

Error: listen EADDRINUSE: address already in use 0.0.0.0:8087

Solution: Use a different port:

npx @gc-mcp/tilt --port 9000

Docker Not Available

Error: Docker is not available. Please install Docker or use --mode node

Solution: Install Docker or use Node mode:

npx @gc-mcp/tilt --mode node

Tilt Not Running

Tilt Status: ❌ Not running

Solution: Start Tilt or check your Tilt configuration:

tilt up

Debugging

Enable verbose logging:

npx @gc-mcp/tilt --env LOG_LEVEL=debug --env VERBOSE=true

Check server status:

npx @gc-mcp/tilt --status

Validate configuration:

npx @gc-mcp/tilt --dry-run

Logs

The server logs are output to stdout/stderr. In Docker mode, you can view container logs:

docker logs mcp-tilt-server

Development

Building from Source

git clone <repository-url>
cd mcp-tilt
npm install
npm run build

Running Tests

npm test
npm run test:e2e

Local Development

npm run dev

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Support

• GitHub Issues
• Documentation