Content
# Claude Code - MCP Hot Reload
[](https://modelcontextprotocol.io)
[](https://www.python.org)
[](LICENSE)
[](https://claude.ai)
Enable hot reloading for MCP (Model Context Protocol) servers during development. Make code changes and restart your servers without losing your Claude Code session.
## Features
- **Seamless Hot Reload** - Restart servers without losing MCP session
- **AI-Triggered Restarts** - Claude can restart servers using the built-in tool
- **Session Preservation** - Maintains connection during restarts
- **Transparent Proxy** - Full MCP protocol support with message forwarding
- **Robust Process Management** - Handles crashes and stuck processes
- **Simple Integration** - Just wrap your existing MCP server command
## Installation
```bash
git clone https://github.com/claude-code-mcp-reload/claude-code-mcp-reload.git
cd claude-code-mcp-reload
pip install -e .
```
## Quick Start
1. Find your Claude configuration file:
- WSL/Linux: `~/.claude.json`
- Windows: Check output of `claude mcp list`
2. Add your server with proxy mode:
```json
{
"mcpServers": {
"my-server": {
"command": "python",
"args": [
"-m",
"mcp_hot_reload",
"wrap",
"--proxy",
"--name",
"my-server",
"--",
"python",
"/path/to/my/server.py"
]
}
}
}
```
3. Start Claude Code and your server will be available with hot reload
4. When you make code changes, ask Claude: "Please restart my-server"
5. Your server restarts while maintaining the connection!
## Usage
### Proxy Mode (Recommended)
The proxy mode acts as transparent middleware between Claude and your MCP server:
```bash
mcp-hot-reload wrap --proxy --name my-server -- python server.py
```
This mode:
- Maintains Claude's connection during restarts
- Automatically adds restart_server tool to your server
- Handles all protocol messages transparently
- Re-initializes the server after restart
### Basic Mode
For simpler use cases, basic mode provides process management with manual reconnection:
```bash
# Wrap your server
mcp-hot-reload wrap --name my-server -- python server.py
# Run helper server (in separate config entry)
mcp-hot-reload helper
```
Note: Basic mode requires restarting Claude Code after each server restart.
### Manual Control
```bash
# Restart a server manually
mcp-hot-reload restart my-server --reason "Updated API endpoints"
# Clean up control files
mcp-hot-reload clean
```
## Configuration Examples
### Windows with WSL Claude
```json
{
"mcpServers": {
"my-api": {
"command": "python.exe",
"args": [
"-m",
"mcp_hot_reload",
"wrap",
"--proxy",
"--name",
"my-api",
"--",
"python.exe",
"C:/Projects/my-api/server.py"
]
}
}
}
```
### Multiple Servers
```json
{
"mcpServers": {
"backend": {
"command": "python",
"args": ["-m", "mcp_hot_reload", "wrap", "--proxy", "--name", "backend", "--", "python", "backend/server.py"]
},
"frontend": {
"command": "python",
"args": ["-m", "mcp_hot_reload", "wrap", "--proxy", "--name", "frontend", "--", "python", "frontend/server.py"]
}
}
}
```
## How It Works
The hot reloader uses a proxy architecture to maintain connections:
1. **Proxy Layer** - Sits between Claude and your MCP server
2. **Message Interception** - Captures and forwards protocol messages
3. **Tool Injection** - Adds restart_server to your server's capabilities
4. **State Preservation** - Maintains session during server restarts
5. **Automatic Re-initialization** - Replays the initialize request after restart
## Advanced Features
- **Graceful Shutdown** - SIGTERM with 5s timeout before force kill
- **Python Cache Clearing** - Automatically removes `__pycache__` directories
- **Restart Throttling** - Prevents restart loops with exponential backoff
- **Process Monitoring** - Tracks server health and restart counts
- **Concurrent Servers** - Support for multiple wrapped servers
## Troubleshooting
**Server not restarting?**
- Verify server is wrapped with `--proxy` flag
- Check server name matches your request
- Use `--verbose` flag for detailed logs
**Connection issues?**
- Ensure you're using proxy mode for session preservation
- Check server output for startup errors
- Verify MCP protocol compatibility
**Permission errors?**
- Check write access to `~/.mcp_hot_reload/`
- Ensure server script has execute permissions
## Disclaimer
THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Users must conduct their own due diligence and testing. The author assumes no responsibility for any loss, harm, or damage resulting from the use of this software. Use at your own risk.
## License
Copyright (c) 2024 Kurt Buhler (Data Goblins). All rights reserved.
This software is licensed for **NON-COMMERCIAL USE ONLY**. Commercial use requires written permission from Kurt Buhler (Data Goblins).
See the LICENSE file for full terms and conditions.
For commercial licensing inquiries, please contact Kurt Buhler at Data Goblins.
