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.

You might use this if…	You want your AI to switch AR lenses, toggle Vtuber avatars, or clear effects during live OBS broadcasts — controlled by Twitch chat events, channel points, or agentic automation.
What it connects to	Streamfog desktop app → Streamer.bot WebSocket → this MCP server
Ports	Backend 10994, Dashboard 10995
Start	just bootstrap then start.ps1

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

Variable	Default	Description
STREAMFOG_MCP_STREAMERBOT_HOST	127.0.0.1	Streamer.bot WebSocket host
STREAMFOG_MCP_STREAMERBOT_PORT	8080	Streamer.bot WebSocket port
STREAMFOG_MCP_STREAMERBOT_TOKEN	—	Streamer.bot auth token
STREAMFOG_MCP_LENS_MAP_PATH	lenses.json	Path to lens→action mapping file
STREAMFOG_MCP_PORT	10994	Backend port

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

Tool	Description
streamfog_set_lens	Activate a specific AR lens or face filter
streamfog_clear_effects	Strip all effects, return camera to baseline
streamfog_toggle_avatar	Toggle Vtuber-style avatar on/off

Discovery — READ_ONLY

Tool	Description
streamfog_list_lenses	List all configured lenses from lenses.json
streamfog_status	Bridge connection health + lens count

REST API

Endpoint	Method	Description
/api/v1/status	GET	Server + bridge health
/api/v1/lenses	GET	List all lenses
/api/v1/lenses/set	POST	Activate a lens ({"lens_identifier": "beauty_smooth"})
/api/v1/lenses/reload	POST	Reload lens map from disk
/api/v1/effects/clear	POST	Clear all effects
/api/v1/avatar/toggle	POST	Toggle avatar

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