Tilt MCP Server

1# Tilt MCP Server
2 
3A Model Context Protocol (MCP) server that integrates with [Tilt](https://tilt.dev/) to provide programmatic access to Tilt resources and logs through LLM applications.
4 
5## Why use a Tilt MCP server?
6 
7Imagine prompting like this:
8 
9> 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.
10 
11The 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.
12 
13Tilt 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.
14 
15This 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.
16 
17## Overview
18 
19The Tilt MCP server allows Large Language Models (LLMs) and AI assistants to interact with your Tilt development environment. It provides tools to:
20 
21- List all enabled Tilt resources
22- Fetch logs from specific resources
23- Monitor resource status and health
24- Enable and disable resources dynamically
25- Get detailed information about resources
26- Trigger resource rebuilds
27- Wait for resources to reach specific conditions
28 
29This enables AI-powered development workflows, debugging assistance, automated monitoring, and intelligent resource management of your Tilt-managed services.
30 
31## Available MCP Capabilities
32 
33The Tilt MCP server follows the Model Context Protocol specification and exposes three types of capabilities:
34 
35### 🔍 Resources (Read-Only Data)
36 
37Resources provide read-only access to Tilt data. They're automatically discovered by MCP clients and can be accessed via their URI.
38 
39| Resource URI | Description |
40|--------------|-------------|
41| `tilt://resources/all{?tilt_port}` | List of all enabled Tilt resources with their current status |
42| `tilt://resources/{resource_name}/logs{?tail,filter,tilt_port}` | Logs from a specific resource with optional regex filtering (case-insensitive by default) |
43| `tilt://resources/{resource_name}/describe{?tilt_port}` | Detailed information about a specific resource |
44 
45All resources support an optional `tilt_port` parameter (default: 10350) to query different Tilt instances.
46 
47**Example URIs:**
48- `tilt://resources/all` - Get all resources from default port (10350)
49- `tilt://resources/all?tilt_port=10351` - Get all resources from port 10351
50- `tilt://resources/frontend/logs` - Get last 1000 lines from frontend (default)
51- `tilt://resources/frontend/logs?tail=100&tilt_port=10351` - Get last 100 lines from frontend on port 10351
52- `tilt://resources/backend/logs?filter=error` - Filter logs for errors (case-insensitive)
53- `tilt://resources/backend/logs?filter=X-Request-Id:%20abc123` - Filter by request ID
54- `tilt://resources/backend/describe` - Get detailed info about backend
55 
56### 🛠️ Tools (Actions with Side Effects)
57 
58Tools enable LLMs to perform actions that modify the state of your Tilt environment.
59 
60| Tool | Description | Parameters |
61|------|-------------|------------|
62| `trigger_resource` | Triggers a Tilt resource to rebuild/update | `resource_name` (required), `tilt_port` (optional, default: '10350') |
63| `enable_resource` | Enables one or more Tilt resources | `resource_names` (required, list), `enable_only` (optional, default: false), `tilt_port` (optional, default: '10350') |
64| `disable_resource` | Disables one or more Tilt resources | `resource_names` (required, list), `tilt_port` (optional, default: '10350') |
65| `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') |
66 
67**Read-Only Tools** (for clients that don't support MCP Resources):
68 
69| Tool | Description | Parameters |
70|------|-------------|------------|
71| `list_resources` | List all enabled Tilt resources with their status | `tilt_port` (optional, default: '10350') |
72| `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') |
73| `describe_resource` | Get detailed information about a specific resource | `resource_name` (required), `tilt_port` (optional, default: '10350') |
74 
75> **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.
76 
77All tools support an optional `tilt_port` parameter to target different Tilt instances running on different ports.
78 
79### 💡 Prompts (Guided Workflows)
80 
81Prompts are reusable templates that guide the LLM through common debugging and troubleshooting workflows.
82 
83| Prompt | Description | Parameters |
84|--------|-------------|------------|
85| `debug_failing_resource` | Step-by-step debugging guide for a failing resource | `resource_name` (required) |
86| `analyze_resource_logs` | Analyze logs from a resource to identify errors | `resource_name` (required), `lines` (optional, default: 100) |
87| `troubleshoot_startup_failure` | Investigate why a resource won't start or keeps crashing | `resource_name` (required) |
88| `health_check_all_resources` | Comprehensive health check across all resources | None |
89| `optimize_resource_usage` | Optimize resource usage by selectively enabling/disabling services | `focus_resources` (required, list) |
90 
91### Error Handling
92 
93All capabilities include comprehensive error handling:
94- **Resource Not Found**: Raises `ValueError` with helpful message
95- **Tilt Connection Issues**: Raises `RuntimeError` with Tilt error details
96- **JSON Parsing Errors**: Provides detailed parsing error information
97 
98All operations are logged to `~/.tilt-mcp/tilt_mcp.log` for debugging.
99 
100## Features
101 
102**MCP Protocol Compliance:**
103- 🔍 **Resources**: Read-only access to Tilt data via URI templates (e.g., `tilt://resources/all`)
104- 🛠️ **Tools**: Actions with side effects for resource management and control
105- 💡 **Prompts**: Guided workflows for debugging and troubleshooting
106 
107**Capabilities:**
108- 📊 **Resource Discovery**: List all active Tilt resources with their current status
109- 📜 **Log Retrieval**: Fetch recent logs from any Tilt resource with configurable tail
110- 🔄 **Resource Triggering**: Manually trigger Tilt resources to rebuild/update
111- ✅ **Resource Control**: Enable or disable resources dynamically
112- 📋 **Detailed Information**: Get comprehensive details about any resource
113- ⏳ **Wait Conditions**: Wait for resources to reach specific states
114- 🤖 **Guided Workflows**: Pre-built prompts for common debugging scenarios
115 
116**Technical Features:**
117- 🛡️ **Type Safety**: Built with Python type hints for better IDE support
118- 🚀 **Async Support**: Fully asynchronous implementation using FastMCP
119- 📈 **MCP Best Practices**: Proper separation of resources, tools, and prompts
120- 🔧 **Comprehensive Logging**: All operations logged to `~/.tilt-mcp/tilt_mcp.log`
121 
122## Prerequisites
123 
124- Python 3.10 or higher (required by FastMCP 2.0)
125- [Tilt](https://docs.tilt.dev/install.html) installed and configured
126- An MCP-compatible client (e.g., Claude Desktop, mcp-cli)
127 
128## Installation
129 
130You can install Tilt MCP in three ways:
131 
132### Option 1: Using Docker (Recommended for macOS/Windows)
133 
134The 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).
135 
136**How it works:**
137- Automatically discovers the Tilt API port from `~/.tilt-dev/config` based on the `tilt_port` parameter
138- Uses `socat` to dynamically create a TCP tunnel from inside the container to the host Tilt server
139- Your host's `~/.tilt-dev` directory is mounted with write access (Tilt CLI needs lock files)
140- A single MCP server can query multiple Tilt instances by specifying different `tilt_port` values (10350, 10351, etc.)
141- The Python code handles port discovery and socat management automatically
142 
143**Note:** The image size is primarily driven by FastMCP 2.0's dependencies (cryptography, pydantic, etc.). For reference:
144- Base Alpine + Python: ~50MB
145- Tilt binary: ~20MB
146- FastMCP 2.0 + dependencies: ~250MB
147 
148See the [MCP Configuration](#configuration) section below for setup instructions.
149 
150### Option 2: From PyPI
151 
152```bash
153pip install tilt-mcp
154```
155 
156**Best for:** Linux users or when you prefer local installation
157 
158### Option 3: From Source
159 
160```bash
161git clone https://github.com/rrmistry/tilt-mcp.git
162cd tilt-mcp
163pip install -e .
164```
165 
166**Best for:** Development or testing local changes
167 
168## Configuration
169 
170### Docker Configuration (Recommended for macOS/Windows)
171 
172Add the following to your Claude Desktop configuration file:
173 
174**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
175**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
176**Linux**: `~/.config/claude/claude_desktop_config.json`
177 
178**For macOS/Linux (single Tilt instance on default port 10350):**
179```json
180{
181  "mcpServers": {
182    "tilt": {
183      "type": "stdio",
184      "command": "docker",
185      "args": [
186        "run",
187        "-i",
188        "--rm",
189        "-v",
190        "${HOME}/.tilt-dev:/home/mcp-user/.tilt-dev",
191        "-v",
192        "${HOME}/.tilt-mcp:/home/mcp-user/.tilt-mcp",
193        "--network=host",
194        "ghcr.io/rrmistry/tilt-mcp:latest"
195      ],
196      "env": {}
197    }
198  }
199}
200```
201 
202**For multiple Tilt instances:**
203 
204A single MCP server can query multiple Tilt instances. Simply specify the `tilt_port` parameter when calling tools or resources:
205 
206```python
207# Query resources from different Tilt instances
208trigger_resource(resource_name="backend", tilt_port="10350")  # First instance
209trigger_resource(resource_name="backend", tilt_port="10351")  # Second instance
210 
211# Get logs from specific instance
212# URI: tilt://resources/backend/logs?tilt_port=10351
213```
214 
215No additional configuration needed - use the same single-instance Docker config above.
216 
217**For Windows (PowerShell):**
218```json
219{
220  "mcpServers": {
221    "tilt": {
222      "type": "stdio",
223      "command": "docker",
224      "args": [
225        "run",
226        "-i",
227        "--rm",
228        "-v",
229        "${env:USERPROFILE}\\.tilt-dev:/home/mcp-user/.tilt-dev",
230        "-v",
231        "${env:USERPROFILE}\\.tilt-mcp:/home/mcp-user/.tilt-mcp",
232        "--network=host",
233        "ghcr.io/rrmistry/tilt-mcp:latest"
234      ],
235      "env": {}
236    }
237  }
238}
239```
240 
241**For Windows (CMD):**
242Use `%USERPROFILE%` instead of `${env:USERPROFILE}` in the volume mount paths.
243 
244**Key Configuration Notes:**
245- The `tilt_port` parameter represents the web UI port (10350, 10351, etc.) - NOT the API port
246- The Python code auto-discovers the actual API port from `~/.tilt-dev/config`
247- Context naming: port 10350 → "tilt-default", port 10351 → "tilt-10351", etc.
248- The `~/.tilt-dev` directory must be mounted with **write access** (Tilt CLI needs lock files)
249- `socat` dynamically forwards the discovered API port to `host.docker.internal`
250- `--network=host` is required for `host.docker.internal` to work on macOS/Windows
251 
252**Environment Variables:**
253 
254| Variable | Default | Description |
255|----------|---------|-------------|
256| `IS_DOCKER_MCP_SERVER` | `false` | Set to `true` when running in Docker (set automatically in the Docker image) |
257| `TILT_MCP_USE_SOCAT` | `auto` | Control socat TCP forwarding behavior (see below) |
258| `TILT_HOST` | `host.docker.internal` | Host to forward to when using socat |
259| `TILT_MCP_LOG_FILE` | (none) | Override log file path (default: `~/.tilt-mcp/tilt_mcp.log`) |
260 
261**TILT_MCP_USE_SOCAT modes:**
262- `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`).
263- `true` or `1`: Always use socat forwarding, even if the port is already accessible.
264- `false` or `0`: Never use socat, even in Docker environments.
265 
266### Local Installation Configuration
267 
268If you installed via PyPI or from source, use this simpler configuration:
269 
270```json
271{
272  "mcpServers": {
273    "tilt": {
274      "command": "tilt-mcp"
275    }
276  }
277}
278```
279 
280Making sure that `tilt-mcp` is in your PATH.
281 
282### For Development/Testing
283 
284You can run the server directly:
285 
286```bash
287python -m tilt_mcp.server
288```
289 
290Or use it with the MCP CLI:
291 
292```bash
293mcp run python -m tilt_mcp.server
294```
295 
296### Checking Version
297 
298To check the installed version of tilt-mcp:
299 
300```bash
301tilt-mcp --version
302```
303 
304### Building Docker Image Locally
305 
306Build the optimized Alpine-based image:
307 
308```bash
309docker build -t ghcr.io/rrmistry/tilt-mcp:latest .
310```
311 
312Or build with a specific Tilt version:
313 
314```bash
315docker build --build-arg TILT_VERSION=0.35.2 -t ghcr.io/rrmistry/tilt-mcp:latest .
316```
317 
318To use Debian instead of Alpine (larger image but better compatibility):
319 
320```bash
321docker build --build-arg BASE_IMAGE=python:3.11-slim-bookworm -t ghcr.io/rrmistry/tilt-mcp:latest .
322```
323 
324## Usage
325 
326Once configured, the Tilt MCP server provides Resources, Tools, and Prompts through the Model Context Protocol.
327 
328### Using Resources
329 
330Resources are read-only and provide direct access to Tilt data. MCP clients can access them via their URI:
331 
332**Get all resources:**
333```
334tilt://resources/all
335```
336Returns:
337```json
338{
339  "resources": [
340    {
341      "name": "frontend",
342      "type": "k8s",
343      "status": "ok",
344      "updateStatus": "ok"
345    },
346    {
347      "name": "backend-api",
348      "type": "k8s",
349      "status": "pending",
350      "updateStatus": "pending"
351    }
352  ],
353  "count": 2
354}
355```
356 
357**Get logs from a resource:**
358```
359tilt://resources/frontend/logs
360```
361Returns the last 1000 lines of logs as plain text (default).
362 
363**Get custom number of log lines:**
364```
365tilt://resources/frontend/logs?tail=50
366```
367Returns the last 50 lines of logs as plain text.
368 
369**Get detailed resource information:**
370```
371tilt://resources/backend/describe
372```
373Returns detailed YAML/text output with configuration, status, and build history.
374 
375### Using Tools
376 
377Tools perform actions that modify the state of your Tilt environment.
378 
379**Trigger a rebuild:**
380```json
381{
382  "name": "trigger_resource",
383  "arguments": {
384    "resource_name": "backend"
385  }
386}
387```
388 
389**Enable specific resources:**
390```json
391{
392  "name": "enable_resource",
393  "arguments": {
394    "resource_names": ["frontend", "backend"],
395    "enable_only": false
396  }
397}
398```
399 
400**Disable resources:**
401```json
402{
403  "name": "disable_resource",
404  "arguments": {
405    "resource_names": ["frontend", "backend"]
406  }
407}
408```
409 
410**Wait for a resource to be ready:**
411```json
412{
413  "name": "wait_for_resource",
414  "arguments": {
415    "resource_name": "backend",
416    "condition": "Ready",
417    "timeout_seconds": 60
418  }
419}
420```
421 
422### Using Prompts
423 
424Prompts provide guided workflows for common tasks. They generate contextual messages that guide the LLM through debugging and troubleshooting.
425 
426**Debug a failing resource:**
427```json
428{
429  "name": "debug_failing_resource",
430  "arguments": {
431    "resource_name": "backend"
432  }
433}
434```
435This generates a comprehensive debugging workflow that guides the LLM to check logs, status, and suggest fixes.
436 
437**Perform a health check:**
438```json
439{
440  "name": "health_check_all_resources",
441  "arguments": {}
442}
443```
444This creates a systematic health check workflow across all resources.
445 
446**Optimize resource usage:**
447```json
448{
449  "name": "optimize_resource_usage",
450  "arguments": {
451    "focus_resources": ["backend", "database"]
452  }
453}
454```
455This guides the LLM to enable only specified resources and disable others to conserve system resources.
456 
457## Example Prompts
458 
459Here are some example prompts you can use with an AI assistant that has access to this MCP server:
460 
461**Using Built-in Prompt Templates:**
462- "Use the debug_failing_resource prompt for the backend service"
463- "Run a health check on all my resources"
464- "Use the troubleshoot_startup_failure prompt to investigate why the frontend won't start"
465- "Analyze the logs from the backend service using the analyze_resource_logs prompt"
466- "Help me optimize my resources to focus on just the backend and database"
467 
468**Resource Discovery & Status:**
469- "Show me all the Tilt resources that are currently running"
470- "Which services are failing or have errors?"
471- "Compare the status of frontend and backend services"
472- "Access the tilt://resources/all resource to see all services"
473 
474**Log Analysis:**
475- "Get the last 100 lines of logs from the backend-api service"
476- "Read the logs from tilt://resources/frontend/logs?tail=50"
477- "Show me the last 200 lines of logs from any failing services"
478- "Help me debug why the frontend service is crashing by looking at recent logs"
479 
480**Resource Control:**
481- "Disable the frontend and backend services"
482- "Enable only the database service and disable everything else"
483- "Enable the frontend service"
484- "Disable all non-essential services to save resources"
485 
486**Build & Deployment:**
487- "Trigger a rebuild of the backend service"
488- "Rebuild the frontend and show me the logs"
489- "Trigger all services that have errors"
490- "Wait for the backend to be ready before checking its logs"
491 
492**Advanced Automation Workflows:**
493- "Enable the backend, wait for it to be ready, then check its logs"
494- "Disable all services, then enable only frontend and wait for it to start"
495- "Get detailed info about the database and show me its recent logs"
496- "Trigger a rebuild of the API service and wait until it's ready"
497- "Run a complete health check and fix any issues you find"
498 
499**Using Resources Directly:**
500- "Read tilt://resources/backend/describe to understand the configuration"
501- "Compare logs from tilt://resources/frontend/logs?tail=500 and tilt://resources/backend/logs?tail=500"
502- "Check tilt://resources/all to see which services need attention"
503- "Get the last 50 lines from the frontend: tilt://resources/frontend/logs?tail=50"
504 
505## Development
506 
507### Setting up the development environment
508 
509```bash
510# Clone the repository
511git clone https://github.com/yourusername/tilt-mcp.git
512cd tilt-mcp
513 
514# Create a virtual environment
515python -m venv venv
516source venv/bin/activate  # On Windows: venv\Scripts\activate
517 
518# Install in development mode with dev dependencies
519pip install -e ".[dev]"
520```
521 
522### Running tests
523 
524```bash
525pytest
526```
527 
528### Code formatting and linting
529 
530```bash
531# Format code
532black src tests
533 
534# Run linter
535ruff check src tests
536 
537# Type checking
538mypy src
539```
540 
541## Troubleshooting
542 
543### Common Issues
544 
5451. **"Tilt not found" error**
546   - Ensure Tilt is installed and available in your PATH
547   - Try running `tilt version` to verify installation
548 
5492. **"No resources found" when Tilt is running**
550   - Make sure your Tiltfile is loaded and resources are started
551   - Check that you're running the MCP server in the correct directory
552 
5533. **Connection errors**
554   - Verify the MCP client configuration is correct
555   - Check the logs at `~/.tilt-mcp/tilt_mcp.log`
556 
5574. **Docker based tilt-mcp not able to connect**
558    - Ensure your `~/.tilt-dev` directory exists and is being created by your Tilt instance
559    - The directory must be mounted with write access: `~/.tilt-dev:/home/mcp-user/.tilt-dev` (Tilt CLI needs lock files)
560    - The `tilt_port` parameter should be your web UI port (10350, 10351, etc.), not the random API port
561    - Check the logs at `~/.tilt-mcp/tilt_mcp.log` to see the discovered API port
562    - The Python code auto-discovers the API port from the config and launches `socat` automatically
563    - Ensure `--network=host` is included in docker args (required for `host.docker.internal`)
564    - If socat is causing issues, you can control it via the `TILT_MCP_USE_SOCAT` environment variable:
565      - `auto` (default): Auto-detects if socat is needed by checking port accessibility
566      - `true`: Force socat on
567      - `false`: Force socat off
568 
5695. **Alpine Linux compatibility**
570    - The Docker image uses Alpine Linux for size optimization
571    - Most Python packages work fine, but if you encounter issues with binary dependencies, you can build using the Debian base by changing the `BASE_IMAGE` build arg to `python:3.11-slim-bookworm`
572 
573### Debug Logging
574 
575The MCP server logs all operations to `~/.tilt-mcp/tilt_mcp.log`. The log includes:
576- Server startup/shutdown events
577- Resource fetch operations
578- Log retrieval operations
579- Error messages with full details
580 
581To enable debug logging, set the environment variable:
582 
583```bash
584export LOG_LEVEL=DEBUG
585```
586 
587**Log Format**: `timestamp - logger_name - level - message`
588 
589**Viewing Logs**:
590```bash
591# View recent logs
592tail -f ~/.tilt-mcp/tilt_mcp.log
593 
594# Search for errors
595grep ERROR ~/.tilt-mcp/tilt_mcp.log
596 
597# View logs from a specific resource fetch
598grep "get_all_resources" ~/.tilt-mcp/tilt_mcp.log
599```
600 
601## Contributing
602 
603We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
604 
605- Setting up your development environment
606- Running tests
607- Submitting pull requests
608- Code style guidelines
609 
610## License
611 
612This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
613 
614## Acknowledgments
615 
616- Built with [FastMCP](https://github.com/jlowin/fastmcp) for the MCP server implementation
617- Integrates with [Tilt](https://tilt.dev/) for Kubernetes development
618 
619## Support
620 
621- 📧 Email: aryan.agrawal@glean.com
622- 💬 Issues: [GitHub Issues](https://github.com/rrmistry/tilt-mcp/issues)
623