Streamfog MCP
![Version]()
![Python]()
![FastMCP]()
![MCP]()
![Ruff]()
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
- Streamfog installed and running
- Streamer.bot installed and running
- Streamfog → Streamer.bot integration enabled in Streamfog's Integrations panel
- Streamer.bot WebSocket server enabled (Settings → WebSocket Server)
- Actions created in Streamer.bot (e.g.
SetLens_BeautySmooth, ClearEffects, ToggleAvatar)
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
