Python MCP Server with HOT Reload 🔥

[CNSeniorious000]

Pre-submission Checklist

• This post follows the MCP community guidelines

What would you like to share?

Introducing mcp-hmr, which is a Python library that provide drop-in replacement for mcp run with fine-grained on-demand hot reload.

pip install mcp-hmr
mcp-hmr path/to/file.py:app

That's it. No config needed. Works with both the official Python SDK and FastMCP v2.

Demo

mcp-inspector-demo.mov

Notice how the server updates instantly without dropping the connection to the client. This is the magic of the underlying HMR library.

Why?

MCP development typically involves frequent iteration on tools, resources, and prompts. Traditional reloaders (like --reload flags) restart the entire process on every file change, forcing:

• Full Python interpreter restart
• Re-importing all third-party packages
• Loss of all application state
• Long startup times for complex servers

With mcp-hmr, only the changed modules and their dependents reload. Everything else stays running. For servers with expensive initialization (loading models, connecting to databases, etc.), this saves significant time.

How it works

Under the hood, mcp-hmr uses:

• hmr - Runtime dependency tracking and reactive module reloading
• FastMCP.mount - Hot swapping of the underlying FastMCP / mcp.server.FastMCP instances

The reloading is fine-grained (only affected modules rerun) and on-demand (only triggered by actual changes).

Usage

If your server instance is app in main.py:

mcp-hmr main:app

Or using file path:

mcp-hmr ./path/to/main.py:app

Both formats work. The server will automatically reload on code changes while maintaining the connection to your MCP client.

Currently only stdio transport is supported.

Example

See the full example in the repo.

from mcp.server.fastmcp import FastMCP

app = FastMCP()

@app.tool()
def echo(message: str):
    return message

@app.resource("example://greet")
def greet():
    return "hello world"

Run with:

mcp-hmr main:app

When modifying the echo tool or greet resource in your editor, the changes take effect immediately without restarting the connection.

Relevant Links

• PyPI: https://pypi.org/project/mcp-hmr/
• Release: https://github.com/promplate/hmr/releases/tag/mcp-hmr/v0.0.2
• Example: https://github.com/promplate/hmr/tree/readme/examples/mcp
• HMR Core: https://github.com/promplate/pyth-on-line/tree/main/packages/hmr

---

Built on top of hmr, which also powers uvicorn-hmr for FastAPI/Starlette applications.

Just like Vite and Vitest bring HMR to JavaScript, hmr brings fine-grained hot reloading to Python. The goal is to make Python development as smooth as modern frontend tooling.