Tilt

Tilt MCP Server

A Model Context Protocol (MCP) server that integrates with Tilt to provide programmatic access to Tilt resources and logs through LLM applications.

Why use a Tilt MCP server?

Imagine prompting like this:

Please work on {some LLM request} and then check tilt MCP for "backend-api" resource logs for compile status. Make sure that "backend-tests" resource is successful with your changes.

The key insight is you no longer need to tell your LLM how to build and deploy your code. Instead, you can simply ask it to what to build and deploy.

Tilt is a powerful tool for working with Docker/Kubernetes workloads. With the Tilt MCP server, you can integrate Tilt's features directly into your workflow using Large Language Models (LLMs) like Claude Code / Codex / Gemini / VS Code Copilot / etc.

This saves significant LLM tokens (and so ⏱️+💰), both by avoiding to give extra context to your LLM on how to build/deploy, and also by avoiding LLMs actually doing the build/deploy. All the LLM needs to know is to make code changes then call the tilt MCP server to get real-time feedback.

Overview

The Tilt MCP server allows Large Language Models (LLMs) and AI assistants to interact with your Tilt development environment. It provides tools to:

• List all enabled Tilt resources
• Fetch logs from specific resources
• Monitor resource status and health
• Enable and disable resources dynamically
• Get detailed information about resources
• Trigger resource rebuilds
• Wait for resources to reach specific conditions

This enables AI-powered development workflows, debugging assistance, automated monitoring, and intelligent resource management of your Tilt-managed services.

Available MCP Capabilities

The Tilt MCP server follows the Model Context Protocol specification and exposes three types of capabilities:

🔍 Resources (Read-Only Data)

Resources provide read-only access to Tilt data. They're automatically discovered by MCP clients and can be accessed via their URI.

All resources support an optional tilt_port parameter (default: 10350) to query different Tilt instances.

Example URIs:

• tilt://resources/all - Get all resources from default port (10350)
• tilt://resources/all?tilt_port=10351 - Get all resources from port 10351
• tilt://resources/frontend/logs - Get last 1000 lines from frontend (default)
• tilt://resources/frontend/logs?tail=100&tilt_port=10351 - Get last 100 lines from frontend on port 10351
• tilt://resources/backend/logs?filter=error - Filter logs for errors (case-insensitive)
• tilt://resources/backend/logs?filter=X-Request-Id:%20abc123 - Filter by request ID
• tilt://resources/backend/describe - Get detailed info about backend

🛠️ Tools (Actions with Side Effects)

Tools enable LLMs to perform actions that modify the state of your Tilt environment.

Read-Only Tools (for clients that don't support MCP Resources):

Note: The read-only tools (list_resources, get_resource_logs, describe_resource) provide the same functionality as the MCP Resources above, but are exposed as tools for better compatibility with LLM clients (like Claude Code) that may not fully support MCP resource discovery.

All tools support an optional tilt_port parameter to target different Tilt instances running on different ports.

💡 Prompts (Guided Workflows)

Prompts are reusable templates that guide the LLM through common debugging and troubleshooting workflows.

Error Handling

All capabilities include comprehensive error handling:

• Resource Not Found: Raises ValueError with helpful message
• Tilt Connection Issues: Raises RuntimeError with Tilt error details
• JSON Parsing Errors: Provides detailed parsing error information

All operations are logged to ~/.tilt-mcp/tilt_mcp.log for debugging.

Features

MCP Protocol Compliance:

• 🔍 Resources: Read-only access to Tilt data via URI templates (e.g., tilt://resources/all)
• 🛠️ Tools: Actions with side effects for resource management and control
• 💡 Prompts: Guided workflows for debugging and troubleshooting

Capabilities:

• 📊 Resource Discovery: List all active Tilt resources with their current status
• 📜 Log Retrieval: Fetch recent logs from any Tilt resource with configurable tail
• 🔄 Resource Triggering: Manually trigger Tilt resources to rebuild/update
• ✅ Resource Control: Enable or disable resources dynamically
• 📋 Detailed Information: Get comprehensive details about any resource
• ⏳ Wait Conditions: Wait for resources to reach specific states
• 🤖 Guided Workflows: Pre-built prompts for common debugging scenarios

Technical Features:

• 🛡️ Type Safety: Built with Python type hints for better IDE support
• 🚀 Async Support: Fully asynchronous implementation using FastMCP
• 📈 MCP Best Practices: Proper separation of resources, tools, and prompts
• 🔧 Comprehensive Logging: All operations logged to ~/.tilt-mcp/tilt_mcp.log

Prerequisites

• Python 3.10 or higher (required by FastMCP 2.0)
• Tilt installed and configured
• An MCP-compatible client (e.g., Claude Desktop, mcp-cli)

Installation

You can install Tilt MCP in three ways:

Option 1: Using Docker (Recommended for macOS/Windows)

The Docker-based installation requires no Python setup and is automatically kept up-to-date with monthly builds. The image is optimized for size using Alpine Linux (~320MB vs 545MB+ for Debian-based images - 41% reduction).

How it works:

• Automatically discovers the Tilt API port from ~/.tilt-dev/config based on the tilt_port parameter
• Uses socat to dynamically create a TCP tunnel from inside the container to the host Tilt server
• Your host's ~/.tilt-dev directory is mounted with write access (Tilt CLI needs lock files)
• A single MCP server can query multiple Tilt instances by specifying different tilt_port values (10350, 10351, etc.)
• The Python code handles port discovery and socat management automatically

Note: The image size is primarily driven by FastMCP 2.0's dependencies (cryptography, pydantic, etc.). For reference:

• Base Alpine + Python: ~50MB
• Tilt binary: ~20MB
• FastMCP 2.0 + dependencies: ~250MB

See the MCP Configuration section below for setup instructions.

Option 2: From PyPI

pip install tilt-mcp

Best for: Linux users or when you prefer local installation

Option 3: From Source

git clone https://github.com/rrmistry/tilt-mcp.git
cd tilt-mcp
pip install -e .

Best for: Development or testing local changes

Configuration

Docker Configuration (Recommended for macOS/Windows)

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

For macOS/Linux (single Tilt instance on default port 10350):

{
  "mcpServers": {
    "tilt": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "${HOME}/.tilt-dev:/home/mcp-user/.tilt-dev",
        "-v",
        "${HOME}/.tilt-mcp:/home/mcp-user/.tilt-mcp",
        "--network=host",
        "ghcr.io/rrmistry/tilt-mcp:latest"
      ],
      "env": {}
    }
  }
}

For multiple Tilt instances:

A single MCP server can query multiple Tilt instances. Simply specify the tilt_port parameter when calling tools or resources:

# Query resources from different Tilt instances
trigger_resource(resource_name="backend", tilt_port="10350")  # First instance
trigger_resource(resource_name="backend", tilt_port="10351")  # Second instance

# Get logs from specific instance
# URI: tilt://resources/backend/logs?tilt_port=10351

No additional configuration needed - use the same single-instance Docker config above.

For Windows (PowerShell):

{
  "mcpServers": {
    "tilt": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "${env:USERPROFILE}\\.tilt-dev:/home/mcp-user/.tilt-dev",
        "-v",
        "${env:USERPROFILE}\\.tilt-mcp:/home/mcp-user/.tilt-mcp",
        "--network=host",
        "ghcr.io/rrmistry/tilt-mcp:latest"
      ],
      "env": {}
    }
  }
}

For Windows (CMD): Use %USERPROFILE% instead of ${env:USERPROFILE} in the volume mount paths.

Key Configuration Notes:

• The tilt_port parameter represents the web UI port (10350, 10351, etc.) - NOT the API port
• The Python code auto-discovers the actual API port from ~/.tilt-dev/config
• Context naming: port 10350 → "tilt-default", port 10351 → "tilt-10351", etc.
• The ~/.tilt-dev directory must be mounted with write access (Tilt CLI needs lock files)
• socat dynamically forwards the discovered API port to host.docker.internal
• --network=host is required for host.docker.internal to work on macOS/Windows

Environment Variables:

…