prodius-mcp 0.2.1692

MCP server shim for Prodius — lets AI agents reach you by voice

prodius-mcp

Let your AI agents reach you by voice.

prodius-mcp is a lightweight MCP server that bridges any MCP-capable AI tool (Claude Code, Cursor, Windsurf, Codex CLI, and more) to the Prodius desktop app. When an agent needs your input, a popup appears on your screen — wherever you are — and you answer by voice. No switching back to the terminal.

It's a thin stdio shim: standard library only, no third-party dependencies, fast startup, and it talks only to the Prodius desktop app running locally on 127.0.0.1.

Requirements

• Python 3.10+
• The Prodius desktop app installed and running, with Voice Bridge enabled in settings.

Install

pip install prodius-mcp

If prodius-mcp isn't found afterwards, make sure the Python environment you installed into is on your PATH — or use pipx install prodius-mcp.

Connect your tool

Claude Code

The quickest start is one command:

claude mcp add prodius -- prodius-mcp

For the full experience (correct agent label in the modal header, automatic conversation reset on /clear), add the block below to your ~/.claude/settings.json instead. The claude mcp add shortcut omits both pieces.

{
  "env": { "PRODIUS_AGENT_NAME": "Claude Code" },
  "mcpServers": {
    "prodius": {
      "command": "prodius-mcp",
      "args": [],
      "env": { "PRODIUS_AGENT_NAME": "Claude Code" }
    }
  },
  "hooks": {
    "SessionStart": [
      { "matcher": "*", "hooks": [{ "type": "command", "command": "prodius-mcp-reset" }] }
    ]
  }
}

The SessionStart hook calls prodius-mcp-reset whenever you run /clear or open a new session so Prodius doesn't carry stale context across conversations. The top-level env makes the agent name visible to that hook.

To enable voice push (microphone stays available between questions so you can speak to Claude anytime, not just when it asks), start Claude with the channels flag:

claude --dangerously-load-development-channels server:prodius

Cursor / Windsurf / any MCP client

Add to your client's MCP config (e.g. ~/.cursor/mcp.json):

{
  "mcpServers": {
    "prodius": { "command": "prodius-mcp" }
  }
}

Codex CLI

[mcp_servers.prodius]
command = "prodius-mcp"
env = { PRODIUS_AGENT_NAME = "Codex CLI" }

Full setup instructions for each tool, including session-reset hooks and optional voice push, live at prodius.ai/connect.

Tools exposed

Tool	What it does
ask_user	Pops a question on your screen and captures your spoken (or typed) reply. Supports optional clickable answer buttons.
notify	Reports a result to you via a desktop overlay — meant as the agent's final action so its response is never invisible.

Configuration

The shim auto-discovers the running Prodius app. You rarely need to set anything, but these environment variables override the defaults:

Variable	Purpose	Default
PRODIUS_MCP_TOKEN	Auth token for the local Prodius server.	Read from the Prodius app's settings.json.
PRODIUS_BASE_URL	Prodius local server URL.	Discovered from settings (http://127.0.0.1:5555).
PRODIUS_AGENT_NAME	Label shown so you know which agent is asking.	Unknown Agent

Console scripts

• prodius-mcp — the MCP server (run by your AI tool, not by hand).

• prodius-mcp-reset — resets the Prodius conversation. Wire it to a Claude Code SessionStart hook (see the snippet above) so a new session doesn't inherit stale context.

• prodius-permission-hook — routes Claude Code tool-approval prompts to the Prodius voice overlay so you can speak "allow" / "deny" from anywhere. Add it as a PreToolUse hook in ~/.claude/settings.json:

  "hooks": {
    "PreToolUse": [
      { "matcher": "*", "hooks": [{ "type": "command", "command": "prodius-permission-hook" }] }
    ]
  }
  

  Falls through to the normal terminal prompt if Prodius isn't running — never blocks you. Full instructions at prodius.ai/connect.

Troubleshooting

• Popup doesn't appear? Confirm the Prodius desktop app is running with Voice Bridge enabled, and that prodius-mcp is on your PATH.
• Agent doesn't receive your answer? Check your microphone works in Prodius (try a normal dictation), then restart your AI tool after editing its config.

License

MIT