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.