MCP HTML Sync Server
About
A real-time HTML syncing server with hot reload capabilities, built using the Model Context Protocol (MCP)
Details
- License
- MIT license
Explore
- Real-time HTML Syncing: Create and update HTML content with instant updates to all connected clients
- WebSocket Hot Reload: All connected browsers automatically refresh when content changes
- Script Management: Add JavaScript scripts to pages, either via CDN URLs or inline content
- Stylesheet Management: Add CSS stylesheets to pages via CDN URLs
- MCP Integration: Designed specifically for AI agents using the Model Context Protocol
- Page Lifecycle Management: Automatic expiration of pages after configurable time periods
- Connection Limits: Configurable maximum page count with automatic cleanup of oldest pages
- Simple API: Easy-to-use MCP tools for page creation, updating, and destruction
- Lightweight: Minimal dependencies and efficient resource usage
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
MCP HTML Sync ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Edit the .env file to configure the server:
Instead of using an .env file, you can pass environment variables directly to the Docker container at runtime:
docker run -p 3000:3000 \
-e SERVER_PORT=3000 \
-e BASE_URL=http://localhost:3000/ \
-e PAGE_MAX_AGE=1h \
-e PAGE_MAX_COUNT=1000 \
yujiosaka/mcp-html-sync-server
This approach is recommended for production deployments as it allows you to configure the server without modifying the container image.
bun install
bun run config
| Option | Description | Default | Format |
|--------|-------------|---------|--------|
| SERVER_HOST | Host address for binding the HTTP server | localhost | hostname |
| SERVER_PORT | Port number for the HTTP server | 3000 | number |
| BASE_URL | Base URL for generating view URLs | http://localhost:3000/ | URL |
| PAGE_MAX_AGE | Maximum age of pages before expiration | 1h | time string (e.g., 1h, 30m, 1d) |
| PAGE_MAX_COUNT | Maximum number of pages to keep | 1000 | number |
For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open Settings (JSON).
Optionally, you can add it to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others.
> Note that the mcp key is not needed in the .vscode/mcp.json file.
{
"mcp": {
"servers": {
"html-sync-server": {
"command": "npx",
"args": ["-y", "mcp-html-sync-server"],
"env": {
"NODE_ENV": "production"
}
}
}
}
}
For Docker installation:
{
"mcp": {
"servers": {
"html-sync-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-p", "3000:3000",
"-e", "SERVER_PORT=3000",
"-e", "BASE_URL=http://localhost:3000/",
"-e", "PAGE_MAX_AGE=1h",
"-e", "PAGE_MAX_COUNT=1000",
"yujiosaka/mcp-html-sync-server"
]
}
}
}
}
```
The server provides the following MCP tools that can be used by AI agents:
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"mcp html sync server": {
"mcp-html-sync-server": {
"command": "docker",
"args": [
"pull",
"yujiosaka/mcp-html-sync-server"
]
}
}
}
}McpServers
{
"mcp-html-sync-server": {
"command": "docker",
"args": [
"pull",
"yujiosaka/mcp-html-sync-server"
]
}
}Code of Conduct | Contributing | Security
A real-time HTML syncing server with hot reload capabilities, built using the Model Context Protocol (MCP). This server enables AI agents to create, update, and destroy HTML pages dynamically, with all connected clients receiving updates in real-time.
Features
- Real-time HTML Syncing: Create and update HTML content with instant updates to all connected clients
- WebSocket Hot Reload: All connected browsers automatically refresh when content changes
- Script Management: Add JavaScript scripts to pages, either via CDN URLs or inline content
- Stylesheet Management: Add CSS stylesheets to pages via CDN URLs
- MCP Integration: Designed specifically for AI agents using the Model Context Protocol
- Page Lifecycle Management: Automatic expiration of pages after configurable time periods
- Connection Limits: Configurable maximum page count with automatic cleanup of oldest pages
- Simple API: Easy-to-use MCP tools for page creation, updating, and destruction
- Lightweight: Minimal dependencies and efficient resource usage
Architecture
flowchart LR
AI[AI Agent] -->|MCP Protocol| MCP[MCP HTML Sync Server]
MCP -->|Create/Update/Destroy/AddScripts/AddStylesheets| PM[Page Manager]
PM -->|Store| Pages[(HTML Pages, Scripts & Stylesheets)]
User[User Browser] -->|HTTP Request| HTTP[HTTP Server]
HTTP -->|Fetch Page, Scripts & Stylesheets| PM
User <-->|WebSocket| WS[WebSocket Server]
WS <-->|Real-time Updates| PM
Installation
Using Docker
docker pull yujiosaka/mcp-html-sync-server
docker run -p 3000:3000 yujiosaka/mcp-html-sync-server
Docker Environment Variables
Instead of using an .env file, you can pass environment variables directly to the Docker container at runtime:
docker run -p 3000:3000 \
-e SERVER_PORT=3000 \
-e BASE_URL=http://localhost:3000/ \
-e PAGE_MAX_AGE=1h \
-e PAGE_MAX_COUNT=1000 \
yujiosaka/mcp-html-sync-server
This approach is recommended for production deployments as it allows you to configure the server without modifying the container image.
Using NPX
NODE_ENV=production npx mcp-html-sync-server
From Source
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
