# Tilt MCP Server
A Model Context Protocol (MCP) server that integrates with [Tilt](https://tilt.dev/) 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](https://docs.tilt.dev/install.html) installed and configured
- An MCP-compatible client (e.g., Claude Desktop, mcp-cli)
## Installation
### From PyPI (recommended)
```bash
pip install tilt-mcp
```
### From Source
```bash
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`
```json
{
"mcpServers": {
"tilt": {
"command": "tilt-mcp"
}
}
}
```
### For Development/Testing
You can run the server directly:
```bash
python -m tilt_mcp.server
```
Or use it with the MCP CLI:
```bash
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:
```json
[
{
"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:
```json
{
"resource_name": "frontend",
"tail": 50
}
```
Example response:
```json
{
"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
```bash
# 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
```bash
pytest
```
### Code formatting and linting
```bash
# 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:
```bash
export LOG_LEVEL=DEBUG
```
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) 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](LICENSE) file for details.
## Acknowledgments
- Built with [FastMCP](https://github.com/jlowin/fastmcp) for the MCP server implementation
- Integrates with [Tilt](https://tilt.dev/) for Kubernetes development
## Support
- 📧 Email: aryan.agrawal@glean.com
- 💬 Issues: [GitHub Issues](https://github.com/aryan-agrawal-glean/tilt-mcp/issues)
- 📖 Docs: [GitHub Wiki](https://github.com/aryan-agrawal-glean/tilt-mcp/wiki)
Raw data
{
"_id": null,
"home_page": null,
"name": "tilt-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mcp, tilt, kubernetes, development, model-context-protocol",
"author": null,
"author_email": "Aryan Agrawal <aryan.agrawal@glean.com>",
"download_url": "https://files.pythonhosted.org/packages/e5/52/2c07b3719c1814b3690af9c37fc6ffd5be78aa6550ed7090e8a98b85940a/tilt_mcp-0.1.3.tar.gz",
"platform": null,
"description": "# Tilt MCP Server\n\nA Model Context Protocol (MCP) server that integrates with [Tilt](https://tilt.dev/) to provide programmatic access to Tilt resources and logs through LLM applications.\n\n## Overview\n\nThe Tilt MCP server allows Large Language Models (LLMs) and AI assistants to interact with your Tilt development environment. It provides tools to:\n\n- List all enabled Tilt resources\n- Fetch logs from specific resources\n- Monitor resource status and health\n\nThis enables AI-powered development workflows, debugging assistance, and automated monitoring of your Tilt-managed services.\n\n## Features\n\n- \ud83d\udd0d **Resource Discovery**: List all active Tilt resources with their current status\n- \ud83d\udcdc **Log Retrieval**: Fetch recent logs from any Tilt resource\n- \ud83d\udee1\ufe0f **Type Safety**: Built with Python type hints for better IDE support\n- \ud83d\ude80 **Async Support**: Fully asynchronous implementation using FastMCP\n- \ud83d\udcca **Structured Output**: Returns well-formatted JSON responses\n\n## Prerequisites\n\n- Python 3.8 or higher\n- [Tilt](https://docs.tilt.dev/install.html) installed and configured\n- An MCP-compatible client (e.g., Claude Desktop, mcp-cli)\n\n## Installation\n\n### From PyPI (recommended)\n\n```bash\npip install tilt-mcp\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/aryan-agrawal-glean/tilt-mcp.git\ncd tilt-mcp\npip install -e .\n```\n\n## Configuration\n\n### For Claude Desktop\n\nAdd the following to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` \n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json` \n**Linux**: `~/.config/claude/claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"tilt\": {\n \"command\": \"tilt-mcp\"\n }\n }\n}\n```\n\n### For Development/Testing\n\nYou can run the server directly:\n\n```bash\npython -m tilt_mcp.server\n```\n\nOr use it with the MCP CLI:\n\n```bash\nmcp run python -m tilt_mcp.server\n```\n\n## Usage\n\nOnce configured, the Tilt MCP server provides the following tools:\n\n### `get_all_resources`\n\nLists all enabled Tilt resources with their current status.\n\nExample response:\n```json\n[\n {\n \"name\": \"frontend\",\n \"type\": \"k8s\",\n \"status\": \"ok\",\n \"updateStatus\": \"ok\"\n },\n {\n \"name\": \"backend-api\",\n \"type\": \"k8s\", \n \"status\": \"pending\",\n \"updateStatus\": \"pending\"\n }\n]\n```\n\n### `get_resource_logs`\n\nFetches recent logs from a specific Tilt resource.\n\nParameters:\n- `resource_name` (string, required): Name of the Tilt resource\n- `tail` (integer, optional): Number of log lines to return (default: 1000)\n\nExample request:\n```json\n{\n \"resource_name\": \"frontend\",\n \"tail\": 50\n}\n```\n\nExample response:\n```json\n{\n \"logs\": \"2024-01-15 10:23:45 INFO Starting server on port 3000\\n2024-01-15 10:23:46 INFO Server ready\"\n}\n```\n\n## Example Prompts\n\nHere are some example prompts you can use with an AI assistant that has access to this MCP server:\n\n- \"Show me all the Tilt resources that are currently running\"\n- \"Get the last 100 lines of logs from the backend-api service\"\n- \"Which services are failing or have errors?\"\n- \"Show me the recent logs from all services that aren't healthy\"\n- \"Help me debug why the frontend service is crashing\"\n\n## Development\n\n### Setting up the development environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/tilt-mcp.git\ncd tilt-mcp\n\n# Create a virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode with dev dependencies\npip install -e \".[dev]\"\n```\n\n### Running tests\n\n```bash\npytest\n```\n\n### Code formatting and linting\n\n```bash\n# Format code\nblack src tests\n\n# Run linter\nruff check src tests\n\n# Type checking\nmypy src\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"Tilt not found\" error**\n - Ensure Tilt is installed and available in your PATH\n - Try running `tilt version` to verify installation\n\n2. **\"No resources found\" when Tilt is running**\n - Make sure your Tiltfile is loaded and resources are started\n - Check that you're running the MCP server in the correct directory\n\n3. **Connection errors**\n - Verify the MCP client configuration is correct\n - Check the logs at `~/.tilt-mcp/tilt_mcp.log`\n\n### Debug Logging\n\nTo enable debug logging, set the environment variable:\n\n```bash\nexport LOG_LEVEL=DEBUG\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:\n\n- Setting up your development environment\n- Running tests\n- Submitting pull requests\n- Code style guidelines\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [FastMCP](https://github.com/jlowin/fastmcp) for the MCP server implementation\n- Integrates with [Tilt](https://tilt.dev/) for Kubernetes development\n\n## Support\n\n- \ud83d\udce7 Email: aryan.agrawal@glean.com\n- \ud83d\udcac Issues: [GitHub Issues](https://github.com/aryan-agrawal-glean/tilt-mcp/issues)\n- \ud83d\udcd6 Docs: [GitHub Wiki](https://github.com/aryan-agrawal-glean/tilt-mcp/wiki) \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model Context Protocol server for Tilt - interact with Tilt resources through MCP",
"version": "0.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/aryan-agrawal-glean/tilt-mcp/issues",
"Documentation": "https://github.com/aryan-agrawal-glean/tilt-mcp#readme",
"Homepage": "https://github.com/aryan-agrawal-glean/tilt-mcp"
},
"split_keywords": [
"mcp",
" tilt",
" kubernetes",
" development",
" model-context-protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d80f954c862cac2af689c507e547a818f0c7c551025a2ef0ec0cb306afefb913",
"md5": "b2344eec046fbf2e95e995fc28296cb4",
"sha256": "75480468b62852e3e6b22bbf0aa6eee11a1e891421ce128e61c8a326158848ad"
},
"downloads": -1,
"filename": "tilt_mcp-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b2344eec046fbf2e95e995fc28296cb4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7368,
"upload_time": "2025-07-15T09:32:26",
"upload_time_iso_8601": "2025-07-15T09:32:26.521144Z",
"url": "https://files.pythonhosted.org/packages/d8/0f/954c862cac2af689c507e547a818f0c7c551025a2ef0ec0cb306afefb913/tilt_mcp-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e5522c07b3719c1814b3690af9c37fc6ffd5be78aa6550ed7090e8a98b85940a",
"md5": "603063869f4a8580535b397f3a8d8bef",
"sha256": "1932885e5be6b3f155319886b8fb1b4b419ba897f0d06e9589122afcaadc811f"
},
"downloads": -1,
"filename": "tilt_mcp-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "603063869f4a8580535b397f3a8d8bef",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8241,
"upload_time": "2025-07-15T09:32:27",
"upload_time_iso_8601": "2025-07-15T09:32:27.795493Z",
"url": "https://files.pythonhosted.org/packages/e5/52/2c07b3719c1814b3690af9c37fc6ffd5be78aa6550ed7090e8a98b85940a/tilt_mcp-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-15 09:32:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aryan-agrawal-glean",
"github_project": "tilt-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tilt-mcp"
}
JSON
