The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Tilt MCP listing page.
A Model Context Protocol (MCP) server that integrates with Tilt to provide programmatic access to Tilt resources and logs through LLM applications.
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.
The Tilt MCP server allows Large Language Models (LLMs) and AI assistants to interact with your Tilt development environment. It provides tools to:
This enables AI-powered development workflows, debugging assistance, automated monitoring, and intelligent resource management of your Tilt-managed services.
The Tilt MCP server follows the Model Context Protocol specification and exposes three types of capabilities:
Resources provide read-only access to Tilt data. They're automatically discovered by MCP clients and can be accessed via their URI.
| Resource URI | Description |
|---|---|
tilt://resources/all{?tilt_port} | List of all enabled Tilt resources with their current status |
tilt://resources/{resource_name}/logs{?tail,filter,tilt_port} | Logs from a specific resource with optional regex filtering (case-insensitive by default) |
tilt://resources/{resource_name}/describe{?tilt_port} | Detailed information about a specific resource |
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 10351tilt://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 10351tilt://resources/backend/logs?filter=error - Filter logs for errors (case-insensitive)tilt://resources/backend/logs?filter=X-Request-Id:%20abc123 - Filter by request IDtilt://resources/backend/describe - Get detailed info about backendTools enable LLMs to perform actions that modify the state of your Tilt environment.
| Tool | Description | Parameters |
|---|---|---|
trigger_resource | Triggers a Tilt resource to rebuild/update | resource_name (required), tilt_port (optional, default: '10350') |
enable_resource | Enables one or more Tilt resources | resource_names (required, list), enable_only (optional, default: false), tilt_port (optional, default: '10350') |
disable_resource | Disables one or more Tilt resources | resource_names (required, list), tilt_port (optional, default: '10350') |
wait_for_resource | Wait for a resource to reach a specific condition | resource_name (required), condition (optional, default: 'Ready', valid values: 'Ready' or 'UpToDate'), timeout_seconds (optional, default: 30), tilt_port (optional, default: '10350') |
Read-Only Tools (for clients that don't support MCP Resources):
| Tool | Description | Parameters |
|---|---|---|
list_resources | List all enabled Tilt resources with their status | tilt_port (optional, default: '10350') |
get_resource_logs | Get logs from a specific resource with optional regex filtering | resource_name (required), tail (optional, default: 1000), filter (optional, regex pattern), tilt_port (optional, default: '10350') |
describe_resource | Get detailed information about a specific resource | resource_name (required), tilt_port (optional, default: '10350') |
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 are reusable templates that guide the LLM through common debugging and troubleshooting workflows.
| Prompt | Description | Parameters |
|---|---|---|
debug_failing_resource | Step-by-step debugging guide for a failing resource | resource_name (required) |
analyze_resource_logs | Analyze logs from a resource to identify errors | resource_name (required), lines (optional, default: 100) |
troubleshoot_startup_failure | Investigate why a resource won't start or keeps crashing | resource_name (required) |
health_check_all_resources | Comprehensive health check across all resources | None |
optimize_resource_usage | Optimize resource usage by selectively enabling/disabling services | focus_resources (required, list) |
All capabilities include comprehensive error handling:
ValueError with helpful messageRuntimeError with Tilt error detailsAll operations are logged to ~/.tilt-mcp/tilt_mcp.log for debugging.
MCP Protocol Compliance:
tilt://resources/all)Capabilities:
Technical Features:
~/.tilt-mcp/tilt_mcp.logYou can install Tilt MCP in three ways:
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:
~/.tilt-dev/config based on the tilt_port parametersocat to dynamically create a TCP tunnel from inside the container to the host Tilt server~/.tilt-dev directory is mounted with write access (Tilt CLI needs lock files)tilt_port values (10350, 10351, etc.)Note: The image size is primarily driven by FastMCP 2.0's dependencies (cryptography, pydantic, etc.). For reference:
See the MCP Configuration section below for setup instructions.
Best for: Linux users or when you prefer local installation
Best for: Development or testing local changes
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):
For multiple Tilt instances:
A single MCP server can query multiple Tilt instances. Simply specify the tilt_port parameter when calling tools or resources:
No additional configuration needed - use the same single-instance Docker config above.
For Windows (PowerShell):
For Windows (CMD):
Use %USERPROFILE% instead of ${env:USERPROFILE} in the volume mount paths.
Key Configuration Notes:
tilt_port parameter represents the web UI port (10350, 10351, etc.) - NOT the API port~/.tilt-dev/config~/.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/WindowsEnvironment Variables:
| Variable | Default | Description |
|---|---|---|
IS_DOCKER_MCP_SERVER | false | Set to true when running in Docker (set automatically in the Docker image) |
TILT_MCP_USE_SOCAT | auto | Control socat TCP forwarding behavior (see below) |
TILT_HOST | host.docker.internal | Host to forward to when using socat |
TILT_MCP_LOG_FILE | (none) | Override log file path (default: ~/.tilt-mcp/tilt_mcp.log) |
TILT_MCP_USE_SOCAT modes:
auto (default): Auto-detect based on port accessibility. Skips socat if Tilt is already reachable on localhost (e.g., Docker on Linux with --network=host).true or 1: Always use socat forwarding, even if the port is already accessible.false or 0: Never use socat, even in Docker environments.If you installed via PyPI or from source, use this simpler configuration:
Making sure that tilt-mcp is in your PATH.
You can run the server directly:
Or use it with the MCP CLI:
To check the installed version of tilt-mcp:
Build the optimized Alpine-based image:
Or build with a specific Tilt version:
To use Debian instead of Alpine (larger image but better compatibility):
Once configured, the Tilt MCP server provides Resources, Tools, and Prompts through the Model Context Protocol.
Resources are read-only and provide direct access to Tilt data. MCP clients can access them via their URI:
Get all resources:
Returns:
Get logs from a resource:
Returns the last 1000 lines of logs as plain text (default).
Get custom number of log lines:
Returns the last 50 lines of logs as plain text.
Get detailed resource information:
Returns detailed YAML/text output with configuration, status, and build history.
Tools perform actions that modify the state of your Tilt environment.
Trigger a rebuild:
Enable specific resources:
Disable resources:
Wait for a resource to be ready:
Prompts provide guided workflows for common tasks. They generate contextual messages that guide the LLM through debugging and troubleshooting.
Debug a failing resource:
This generates a comprehensive debugging workflow that guides the LLM to check logs, status, and suggest fixes.
Perform a health check:
This creates a systematic health check workflow across all resources.
Optimize resource usage:
This guides the LLM to enable only specified resources and disable others to conserve system resources.
Here are some example prompts you can use with an AI assistant that has access to this MCP server:
Using Built-in Prompt Templates:
Resource Discovery & Status:
Log Analysis:
Resource Control:
Build & Deployment:
Advanced Automation Workflows:
Using Resources Directly:
"Tilt not found" error
tilt version to verify installation"No resources found" when Tilt is running
Connection errors
~/.tilt-mcp/tilt_mcp.logDocker based tilt-mcp not able to connect
~/.tilt-dev directory exists and is being created by your Tilt instance~/.tilt-dev:/home/mcp-user/.tilt-dev (Tilt CLI needs lock files)tilt_port parameter should be your web UI port (10350, 10351, etc.), not the random API port~/.tilt-mcp/tilt_mcp.log to see the discovered API portsocat automatically--network=host is included in docker args (required for host.docker.internal)TILT_MCP_USE_SOCAT environment variable:
auto (default): Auto-detects if socat is needed by checking port accessibilitytrue: Force socat onfalse: Force socat offAlpine Linux compatibility
BASE_IMAGE build arg to python:3.11-slim-bookwormThe MCP server logs all operations to ~/.tilt-mcp/tilt_mcp.log. The log includes:
To enable debug logging, set the environment variable:
Log Format: timestamp - logger_name - level - message
Viewing Logs:
We welcome contributions! Please see our Contributing Guide for details on:
This project is licensed under the MIT License - see the LICENSE file for details.