Tilt Server

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

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

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

Features

• 🔍 Resource Discovery: List all active Tilt resources with their current status
• 📜 Log Retrieval: Fetch recent logs from any Tilt resource
• 🛡️ Type Safety: Built with Python type hints for better IDE support
• 🚀 Async Support: Fully asynchronous implementation using FastMCP
• 📊 Structured Output: Returns well-formatted JSON responses

Prerequisites

• Python 3.8 or higher
• Tilt installed and configured
• An MCP-compatible client (e.g., Claude Desktop, mcp-cli)

Installation

From PyPI (recommended)

pip install tilt-mcp

From Source

git clone https://github.com/aryan-agrawal-glean/tilt-mcp.git
cd tilt-mcp
pip install -e .

Configuration

For Claude Desktop

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

{
  "mcpServers": {
    "tilt": {
      "command": "tilt-mcp"
    }
  }
}

For Development/Testing

You can run the server directly:

python -m tilt_mcp.server

Or use it with the MCP CLI:

mcp run python -m tilt_mcp.server

Usage

Once configured, the Tilt MCP server provides the following tools:

get_all_resources

Lists all enabled Tilt resources with their current status.

Example response:

[
  {
    "name": "frontend",
    "type": "k8s",
    "status": "ok",
    "updateStatus": "ok"
  },
  {
    "name": "backend-api",
    "type": "k8s", 
    "status": "pending",
    "updateStatus": "pending"
  }
]

get_resource_logs

Fetches recent logs from a specific Tilt resource.

Parameters:

• resource_name (string, required): Name of the Tilt resource
• tail (integer, optional): Number of log lines to return (default: 1000)

Example request:

{
  "resource_name": "frontend",
  "tail": 50
}

Example response:

{
  "logs": "2024-01-15 10:23:45 INFO Starting server on port 3000\n2024-01-15 10:23:46 INFO Server ready"
}

Example Prompts

Here are some example prompts you can use with an AI assistant that has access to this MCP server:

• "Show me all the Tilt resources that are currently running"
• "Get the last 100 lines of logs from the backend-api service"
• "Which services are failing or have errors?"
• "Show me the recent logs from all services that aren't healthy"
• "Help me debug why the frontend service is crashing"

Development

Setting up the development environment

# Clone the repository
git clone https://github.com/yourusername/tilt-mcp.git
cd tilt-mcp

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Running tests

pytest

Code formatting and linting

# Format code
black src tests

# Run linter
ruff check src tests

# Type checking
mypy src

Troubleshooting

Common Issues

1. "Tilt not found" error

   • Ensure Tilt is installed and available in your PATH
   • Try running tilt version to verify installation

2. "No resources found" when Tilt is running

   • Make sure your Tiltfile is loaded and resources are started
   • Check that you're running the MCP server in the correct directory

3. Connection errors

   • Verify the MCP client configuration is correct
   • Check the logs at ~/.tilt-mcp/tilt_mcp.log

Debug Logging

To enable debug logging, set the environment variable:

export LOG_LEVEL=DEBUG

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Setting up your development environment
• Running tests
• Submitting pull requests
• Code style guidelines

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with FastMCP for the MCP server implementation
• Integrates with Tilt for Kubernetes development

Support

• 📧 Email: [email protected]
• 💬 Issues: GitHub Issues
• 📖 Docs: GitHub Wiki