MagicMirror MCP Server

A Model Context Protocol (MCP) server that lets AI agents control a MagicMirror² installation and optionally integrate with Home Assistant. AI Agent Integration : This server is designed from the ground up for AI agent control. By exposing MagicMirror and Home Assistant capabilities as structured MCP tools, any compatible AI agent — including Claude — can discover, reason about, and act on your smart display and home devices through natural language. The system.schema tool lets an agent automatically understand what modules and entities are available without any manual configuration. The plugin architecture means new capabilities can be added as isolated plugins without touching core server code, making it straightforward to extend the server for custom modules, third-party services, or entirely new integrations. Whether you want the mirror to react to a Home Assistant automation, display a reminder on demand, or respond to voice commands through an AI assistant, this server provides the connective layer to make it work.

Built with the official MCP TypeScript SDK and designed to run alongside MagicMirror using MMM-Remote-Control.

Features

Module control — list, show, and hide any installed MagicMirror module
Monitor control — turn the display on/off and query its power state
Notifications & alerts — send notifications or display alert popups on the mirror
Mirror health — check connectivity and measure API latency
Home Assistant integration — get entity states, call services, bulk-query entities
System discovery — query installed modules and HA entities in a single call
Plugin architecture — add new tools without touching core code

MCP Tools

| Tool | Description | |---|---| | mirror.module.list | List all installed modules and their visibility state | | mirror.module.show | Show a hidden module by identifier | | mirror.module.hide | Hide a visible module by identifier | | mirror.monitor.on | Turn the display on | | mirror.monitor.off | Turn the display off | | mirror.monitor.status | Get current monitor power state | | mirror.restart | Restart the MagicMirror application | | mirror.health | Check if the mirror is reachable and measure latency | | mirror.notification.send | Send any MagicMirror notification with optional payload | | mirror.alert.show | Display an alert popup (title + message + optional timer) | | mirror.alert.hide | Dismiss the current alert popup | | homeassistant.entity.get | Get state and attributes of a single HA entity | | homeassistant.entities.list | Bulk-get the state of multiple HA entities | | homeassistant.service.call | Call any Home Assistant service | | system.schema | Discover all available modules and HA entities |

Architecture

AI Agent (Claude, etc.)
        │
        ▼
  MCP Server (stdio)
        │
   ┌────┴─────────────────┐
   │                      │
MagicMirror²        Home Assistant
(MMM-Remote-Control)   (REST API)

src/
├── server.ts                  ← Entry point, MCP server init
├── pluginLoader.ts            ← Loads all plugins at startup
├── client/
│   ├── MagicMirrorClient.ts   ← HTTP client for MMM-Remote-Control
│   └── HomeAssistantClient.ts ← HTTP client for Home Assistant REST API
├── plugins/
│   ├── plugin.ts              ← MCPPlugin interface
│   ├── mirrorPlugin.ts        ← Module, monitor, health, and restart tools
│   ├── notificationsPlugin.ts ← Notification and alert tools
│   ├── homeAssistantPlugin.ts ← Home Assistant entity and service tools
│   └── systemPlugin.ts        ← System discovery tool
└── services/
    ├── connectionManager.ts   ← Online/offline state tracking
    ├── discoveryService.ts    ← Queries modules and HA entities
    ├── mirrorObserver.ts      ← Polls mirror for visibility changes
    └── schemaGenerator.ts     ← Builds system capability snapshot

Requirements

Node.js 18+
MagicMirror² with MMM-Remote-Control installed

Optional:

Home Assistant for smart home integration

Installation

git clone https://github.com/Ragziesoft/magicmirror-mcp.git
cd magicmirror-mcp
npm install
npm run build

Configuration

Copy .env.example to .env and fill in your values:

cp .env.example .env

# MagicMirror connection (required)
MAGICMIRROR_URL=http://mirror.local:8080
MAGICMIRROR_API_KEY=your_api_key

# Home Assistant (optional)
HOMEASSISTANT_URL=http://homeassistant.local:8123
HOMEASSISTANT_TOKEN=your_long_lived_token

The API key is configured in MMM-Remote-Control's module settings in your MagicMirror config.js.

Running

npm start

The server communicates over stdio and is designed to be launched by an MCP client (e.g. Claude Desktop, Claude Code).

Claude Desktop config example

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "magicmirror": {
      "command": "node",
      "args": ["/path/to/magicmirror-mcp/dist/server.js"],
      "env": {
        "MAGICMIRROR_URL": "http://mirror.local:8080",
        "MAGICMIRROR_API_KEY": "your_api_key",
        "HOMEASSISTANT_URL": "http://homeassistant.local:8123",
        "HOMEASSISTANT_TOKEN": "your_token"
      }
    }
  }
}

Example AI interactions

"Show the weather module" → mirror.module.show
"Turn off the display at bedtime" → mirror.monitor.off
"Display a reminder: Dinner at 7pm" → mirror.alert.show
"Is the mirror online?" → mirror.health
"Turn on the living room lights" → homeassistant.service.call
"What modules are installed?" → mirror.module.list
"What can you control?" → system.schema

Extending with plugins

Create a new file in src/plugins/ implementing MCPPlugin:

import { z } from "zod"
import { MCPPlugin } from "./plugin.js"

const myPlugin: MCPPlugin = {
  name: "my-plugin",
  async register(server, context) {
    server.tool(
      "my.tool",
      "Description of what this tool does",
      { param: z.string().describe("A parameter") },
      async ({ param }) => {
        return { content: [{ type: "text", text: `Result: ${param}` }] }
      }
    )
  }
}

export default myPlugin

Then add it to src/pluginLoader.ts.

Roadmap

WebSocket support for real-time mirror event streaming
Raspberry Pi shutdown tool
MagicMirror configuration file editing
Camera stream integration
Additional plugin ecosystem

License

MIT

MCP Servers