roam-fm-mcp 0.1.0

MCP server for controlling Roam FM radio app via AI assistants like Claude

Roam FM MCP Server

MCP (Model Context Protocol) server for controlling Roam FM radio app via AI assistants like Claude.

Prerequisites

• macOS
• Roam FM app installed and running
• MCP remote control enabled in Roam FM: Settings > Labs > AI Remote Control
• Python 3.10+

Installation

cd mcp-server
pip install -e .

Configuration

Claude Code

Add to your Claude Code MCP settings (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "roam-fm": {
      "command": "roam-fm-mcp"
    }
  }
}

Or if using a virtual environment:

{
  "mcpServers": {
    "roam-fm": {
      "command": "/path/to/venv/bin/roam-fm-mcp"
    }
  }
}

Available Tools

Tool	Description
roam_play	Start playing radio. Optionally filter by country code.
roam_pause	Pause the current station.
roam_resume	Resume playback.
roam_next	Skip to next random station.
roam_stop	Stop playback completely.
roam_status	Get current playback status and station info.
roam_get_stats	Get listening statistics.

Country Codes

Use ISO 3166-1 alpha-2 country codes for filtering:

• JP - Japan
• US - United States
• FR - France
• DE - Germany
• GB - United Kingdom
• CN - China
• etc.

Example Usage

Ask your AI assistant:

• "Play Japanese radio stations"
• "Pause the radio"
• "What's currently playing?"
• "Skip to the next station"
• "How long have I been listening?"

How It Works

AI Assistant ──MCP──> roam-fm-mcp ──URL Scheme──> Roam FM App
                                  <──status.json──

1. AI sends commands via MCP protocol
2. MCP server triggers URL Scheme (roam-fm://play, etc.)
3. Roam FM app executes the command
4. App writes status to ~/.roam-fm/status.json
5. MCP server reads status and returns result

Troubleshooting

"Status file not found"

Make sure MCP remote control is enabled in Roam FM:

1. Open Roam FM
2. Go to Settings > Labs
3. Enable "AI Remote Control"

Commands not working

1. Check if Roam FM is running
2. Verify the app is responding to URL schemes:

   open "roam-fm://play"
   

3. Check status file exists:

   cat ~/.roam-fm/status.json
   

License

MIT