# Build your own integration

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

## Install dependencies

```bash
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".

```python
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

```python
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

```python
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:

```bash
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.