Streamfog

📖 Installation Guide — quick start, manual setup, and troubleshooting

AI-driven AR lens orchestrator for live OBS streams. Control Streamfog face filters, AR effects, and Vtuber avatars through MCP tools via the local Streamer.bot WebSocket bridge. Your AI assistant becomes a stream producer.

Architecture

┌─────────────┐     MCP SSE      ┌──────────────────┐     WebSocket      ┌──────────────┐
│  LLM Agent  │ ───────────────→ │  streamfog-mcp   │ ────────────────→ │ Streamer.bot  │
│  (Claude,   │ ←─────────────── │  :10994 (FastMCP) │ ←──────────────── │ :8080         │
│   Gemini)   │   JSON-RPC stdio │  :10995 (React)   │   DoAction JSON   │               │
└─────────────┘                  └──────────────────┘                    └──────┬────────┘
                                                                               │ Native Hook
                                                                        ┌──────▼────────┐
                                                                        │  Streamfog    │
                                                                        │  Desktop App  │
                                                                        └──────┬────────┘
                                                                               │ Browser Source
                                                                        ┌──────▼────────┐
                                                                        │  OBS Studio   │
                                                                        └───────────────┘

Quick Start

uv sync
# Edit lenses.json with your Streamer.bot action names
# Set STREAMFOG_MCP_STREAMERBOT_TOKEN in .env if using auth
.\start.ps1

MCP-only via stdio (for Cursor, Claude Desktop):

uv run -m streamfog_mcp --stdio

Prerequisites

1. Streamfog installed and running
2. Streamer.bot installed and running
3. Streamfog → Streamer.bot integration enabled in Streamfog's Integrations panel
4. Streamer.bot WebSocket server enabled (Settings → WebSocket Server)
5. Actions created in Streamer.bot (e.g. SetLens_BeautySmooth, ClearEffects, ToggleAvatar)
6. lenses.json populated with your action→lens mappings

Configuration

Lens Map (lenses.json)

{
  "beauty_smooth": "SetLens_BeautySmooth",
  "cyber_helmet": "SetLens_CyberHelmet",
  "vtuber_avatar": "SetLens_VTuberAvatar"
}

Keys are human-readable lens identifiers used in MCP tool calls. Values are the corresponding Streamer.bot action names.

MCP Tools (5)

Lens Control

Discovery — READ_ONLY

REST API

Web Dashboard

Single-page dark dashboard at :10995:

• Connection status indicator (Streamer.bot bridge health)
• Lens grid with one-click activation
• Quick action buttons (Clear Effects, Toggle Avatar)
• Lens map reload
• Auto-refresh every 5 seconds

Project Structure

streamfog-mcp/
├── src/streamfog_mcp/
│   ├── _mcp.py              FastMCP singleton
│   ├── server.py            Unified FastAPI + FastMCP gateway
│   ├── __main__.py           CLI entry (--stdio / --serve)
│   ├── config.py             Pydantic settings (STREAMFOG_MCP_ prefix)
│   ├── tools/
│   │   ├── __init__.py       Portmanteau import
│   │   └── core_tools.py     5 @mcp.tool() decorators
│   └── services/
│       └── streamerbot.py    Streamer.bot WebSocket client
├── webapp/                   Vite + React 19 + Tailwind
│   └── src/
│       └── pages/Dashboard.tsx
├── lenses.json               Lens → action mapping
├── pyproject.toml
├── start.ps1 / start.bat
├── justfile
└── tests/
    └── test_basic.py         5 tests

Known Limitations

• Streamfog does not expose a native CLI or local API — all control goes through Streamer.bot
• Lens activation is fire-and-forget (Streamer.bot does not report success/failure for actions)
• No lens preview or thumbnail retrieval (Streamfog desktop is a black box)
• Lumia/Crowd Control bridge path is documented but not yet implemented as an alternative transport