Build your own integration

Create a custom MCP server and connect it to VoiceOS in 3 steps.

Install dependencies

pip install mcp
git npm install @modelcontextprotocol/sdk zod

Create your server

An MCP server exposes tools that VoiceOS can call by voice. Pick an example to start from:

• Quick Start
• Home Control
• Spotify
• System Control

Example 1: Home Control

A minimal MCP server with one tool. The fastest way to understand the pattern.

Control HomeKit devices via Apple Shortcuts. Say "turn off the lights" or "set thermostat to 72".

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-tools")

@mcp.tool()
def greet(name: str) -> str:
    """Say hello to someone by name."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run(transport="stdio")

Example 2: Control Spotify

import subprocess
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("spotify")

def osascript(cmd: str) -> str:
    result = subprocess.run(
        ["osascript", "-e", f'tell application "Spotify" to {cmd}"],
        capture_output=True, text=True,
    )
    return result.stdout.strip() or "Done"

@mcp.tool()
def play() -> str:
    """Resume Spotify playback."""
    return osascript("play")

if __name__ == "__main__":
    mcp.run(transport="stdio")

Example 3: System Control

import subprocess
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("system-control")

def osascript(script: str) -> str:
    result = subprocess.run(
        ["osascript", "-e", script],
        capture_output=True, text=True,
    )
    return result.stdout.strip() or "Done"

@mcp.tool()
def set_volume(level: int) -> str:
    """Set the system volume (0-100)."""
    return osascript(f"set volume output volume {level}")

if __name__ == "__main__":
    mcp.run(transport="stdio")

Connect to VoiceOS

Open VoiceOS, go to Settings → Integrations → Custom Integrations, click Add, give it a name, and set the launch command to:

python3 /path/to/my_mcp_server.py
npx tsx /path/to/my-mcp-server.ts
python3 /path/to/home_control.py
npx tsx /path/to/home-control.ts
python3 /path/to/spotify_mcp.py
npx tsx /path/to/spotify-mcp.ts
python3 /path/to/system_control.py
npx tsx /path/to/system-control.ts

Replace /path/to/ with the actual path to your file.