Zaparoo MCP

An MCP server for controlling Zaparoo devices, allowing AI assistants to interact with Zaparoo.

Quick Start

npx -y zaparoo-mcp

By default, devices on the local network are discovered automatically via mDNS. To specify devices manually:

npx -y zaparoo-mcp --devices 192.168.1.100

Configuration

Claude Code

claude mcp add zaparoo -- npx -y zaparoo-mcp

With manual device configuration:

claude mcp add zaparoo --env ZAPAROO_DEVICES=192.168.1.100 -- npx -y zaparoo-mcp

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "zaparoo": {
      "command": "npx",
      "args": ["-y", "zaparoo-mcp"]
    }
  }
}

Codex

codex mcp add zaparoo -- npx -y zaparoo-mcp

Or add to ~/.codex/config.toml:

[mcp_servers.zaparoo]
command = "npx"
args = ["-y", "zaparoo-mcp"]

OpenClaw

openclaw mcp set zaparoo '{"command":"npx","args":["-y","zaparoo-mcp"]}'

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "zaparoo": {
      "command": "npx",
      "args": ["-y", "zaparoo-mcp"]
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "zaparoo": {
      "command": "npx",
      "args": ["-y", "zaparoo-mcp"]
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "zaparoo": {
      "command": "npx",
      "args": ["-y", "zaparoo-mcp"]
    }
  }
}

Options

By default, the server discovers Zaparoo devices on the local network using mDNS. No configuration is needed if your devices are on the same network.

To manually specify devices, use CLI arguments or environment variables. CLI arguments take precedence.

Setting	CLI Argument	Environment Variable
Devices	`--devices host:port[,host:port,...]`	`ZAPAROO_DEVICES`
API keys	`--keys key1[,key2,...]`	`ZAPAROO_KEYS`
No discovery	`--no-discovery`	`ZAPAROO_NO_DISCOVERY=1`

The default port is 7497 if not specified. When devices are specified manually, mDNS discovery is disabled.

Features

Tools

Category	Tools
Launch & Control	`zaparoo_run`, `zaparoo_stop`, `zaparoo_media_control`, `zaparoo_input`
Media Library	`zaparoo_media`, `zaparoo_media_index`, `zaparoo_systems`
NFC & Tokens	`zaparoo_readers`, `zaparoo_readers_write`, `zaparoo_tokens`, `zaparoo_mappings`
Device Management	`zaparoo_devices`, `zaparoo_settings`, `zaparoo_settings_update`, `zaparoo_admin`, `zaparoo_admin_manage`, `zaparoo_screenshot`
Monitoring	`zaparoo_notifications`, `zaparoo_logs`, `zaparoo_inbox`

Resources

zaparoo://devices — all connected device states
zaparoo://{deviceId}/state — per-device state (readers, active media, tokens)
zaparoo://reference/zapscript — ZapScript language reference

Prompts

Write NFC Tag — search for a game and write it to an NFC tag
Find & Launch Game — search your library and launch a game
Create Token Mapping — map NFC token scans to actions
Review Play History — play statistics and recent activity
What's Playing? — quick status dashboard of all devices
Explore Game Library — browse games, get recommendations, discover hidden gems
ZapScript Help — help composing ZapScript commands

Prerequisites

Node.js 22+
One or more Zaparoo Core devices accessible on the network

Development

git clone https://github.com/ZaparooProject/zaparoo-mcp.git
cd zaparoo-mcp
npm install
npm run build

Command	Description
`npm run dev`	Build in watch mode
`npm run lint:fix`	Auto-fix lint issues
`npm run format`	Format code
`npm test`	Run tests
`npm run test:watch`	Tests in watch mode

License

This project is licensed under the GNU General Public License v3.0 or later.

zaparoo-mcp

Quick Install