Kindle MCP Dashboard

An MCP-controlled, server-rendered e-ink dashboard for the Amazon Kindle Paperwhite EY21 (Paperwhite 1, 2012). The renderer targets its 758×1024, 16-level grayscale display and deliberately sends the Kindle a simple PNG.

The Kindle is a display client, not the MCP host:

Claude / Pi / another MCP client
             │ MCP tools
             ▼
   dashboard state + renderer ──── HTTP ────► Kindle EY21

This separation keeps API keys and integrations off the old device. MCP clients can design screens and push weather, hardware, home automation, or agent-control plane state. Live host time and hardware utilization are resolved when the PNG is rendered.

Features

• Named screens with an active-screen switch

• Regions positioned on a normalized 1000×1000 canvas

• text, metric, status, progress, list, and local image widgets

• Built-in monochrome icons: weather/cloud, cpu, memory, disk, agent

• Atomic JSON persistence shared by the MCP and HTTP processes

• Live sources: system.time, system.date, system.hostname, system.cpu_percent, system.memory_percent, system.disk_percent, system.load, and system.uptime

• Browser mode with cache-free periodic refresh

• Optional jailbroken-device wget + eips refresh script

Related MCP server: Send to Kindle MCP Server

Install and run

cd kindle-mcp-dashboard
python -m venv .venv
.venv/bin/pip install -e .
.venv/bin/kindle-dashboard init
.venv/bin/kindle-dashboard preview
.venv/bin/kindle-dashboard serve --host 0.0.0.0 --port 8787 --refresh 60

Port 8787 is the direct dashboard-server port. Find the computer's LAN address with ip -br address. Most clients can open this plain-HTTP URL in the Experimental Browser:

http://COMPUTER_LAN_IP:8787/kindle

For the first-generation EY21 on firmware 5.6.1.1, the Experimental Browser and the jailbroken device client were tested successfully through standard HTTP port 80 instead. Configure a reverse proxy from port 80 to the dashboard's 8787 port, then use:

http://COMPUTER_LAN_IP/kindle

Store connectivity and Amazon registration are not required. The browser only needs working local Wi-Fi. If the browser itself cannot open local HTTP pages, use the optional jailbroken client described below.

Connect an MCP client

The MCP server uses stdio. Example Claude Code registration:

claude mcp add kindle-dashboard -- \
  /absolute/path/to/kindle-mcp-dashboard/.venv/bin/kindle-dashboard-mcp

Example Codex registration:

codex mcp add kindle-dashboard -- \
  /absolute/path/to/kindle-mcp-dashboard/.venv/bin/kindle-dashboard-mcp

Equivalent generic MCP client configuration:

{
  "mcpServers": {
    "kindle-dashboard": {
      "command": "/absolute/path/to/kindle-mcp-dashboard/.venv/bin/kindle-dashboard-mcp"
    }
  }
}

Then ask the agent, for example:

Update the Kindle overview weather region to show Lisbon, 21 °C, partly cloudy. Replace the agent list with Codex running, Claude idle, and CI healthy.

The MCP tools are:

• get_dashboard

• list_screens

• activate_screen

• upsert_screen

• update_region

• push_updates

• render_preview

For layout changes, use upsert_screen. Coordinates are normalized: {x: 0, y: 0, w: 500, h: 500} is the top-left quarter regardless of device pixels. Content-only updates should use update_region or atomic push_updates. Image regions use an absolute local file path in their image field; the image must be available on the machine running the renderer. Set trim: true to remove white margins before fitting a logo or other scanned asset.

Example update arguments:

{
  "screen_id": "overview",
  "updates": [
    {
      "region_id": "weather",
      "fields": {"value": "21 °C · partly cloudy", "icon": "cloud"}
    },
    {
      "region_id": "agents",
      "fields": {
        "items": [
          {"text": "Codex · running tests", "status": "running"},
          {"text": "Claude · idle", "status": "idle"},
          {"text": "CI · healthy", "status": "healthy"}
        ]
      }
    }
  ]
}

Optional jailbroken EY21 mode

This device is confirmed as firmware 5.6.1.1, build 2689890035. See the firmware-specific deployment notes. Its B024 serial prefix confirms the Wi-Fi Paperwhite 1 variant. The current KindleModding compatibility data selects WinterBreak2 for this model and firmware, without a registration or lock-screen-ad prerequisite.

B024 is a non-unique model-family prefix used only for compatibility lookup; the dashboard never needs or stores a complete Kindle serial number. Users with a different device should select or create a matching profile rather than publishing their full serial.

Once the EY21 is already jailbroken with shell access, copy kindle/refresh.sh to it, make it executable, and change DASHBOARD_URL to the server's LAN address. For this firmware, use the port-80 /screen.png URL from the supplied dashboard.conf; the direct :8787 endpoint was not reliable on the device. The script disables the screensaver, downloads the current PNG, and draws it using the Kindle's built-in eips command.

The original Paperwhite is also supported by the legacy kindle build of KOReader, which can be useful as a launcher on an already-jailbroken device.

State and operation

State defaults to:

~/.local/state/kindle-mcp-dashboard/dashboard.json

Override it for both processes with KINDLE_DASHBOARD_STATE. Run the HTTP server and MCP server under the same Unix user so they share the same file.

The browser refresh interval defaults to 60 seconds. E-ink panels ghost when updated too often, so intervals below 30 seconds are discouraged. The HTTP server enforces a minimum browser refresh of 10 seconds.

The HTTP display server has no authentication. When bound to 0.0.0.0, its screen image and /api/state are readable by other devices that can reach the port. Run it only on a trusted LAN or restrict access with a host firewall.

Development

.venv/bin/pip install pytest
.venv/bin/pytest