Streamfog MCP
The Streamfog MCP server enables AI assistants and scripts to control AR lenses, face filters, and Vtuber avatars in live streams by bridging commands to Streamer.bot. You can:
Activate AR lenses or face filters using
streamfog_set_lens, specifying a lens identifier (e.g.,beauty_smooth,cyber_helmet) from the locallenses.jsonmapping.Clear all effects via
streamfog_clear_effectsto remove active AR assets and return to a clean camera feed.Toggle Vtuber avatars with
streamfog_toggle_avatarto turn the avatar overlay on or off (activates the default avatar if none is active).List available lenses using
streamfog_list_lenses, which retrieves all configured lenses and their action names, with an option to reload from disk.Check bridge connection status via
streamfog_status, showing connectivity to Streamer.bot, loaded lens count, and recent errors.Access a REST API for programmatic control, health checks, lens management, and logs.
Use a web dashboard at port 10995 for manual interaction, including lens selection, status KPIs, and local LLM chat.
Run the server in dual mode (stdio or HTTP) to integrate with MCP clients like Claude or Cursor.
Allows controlling AR lenses, face filters, Vtuber avatars, and effects in OBS Studio via Streamfog and Streamer.bot during live broadcasts.
Enables AI agents to trigger lens switches, avatar toggles, and effect clears on Twitch streams using chat events and channel points.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Streamfog MCP switch to the cyber helmet lens"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Streamfog MCP
π Installation Guide β quick start, manual setup, and troubleshooting π Docs β Configuration Β· Tools Β· Troubleshooting Β· Development π€ llms-full.txt β full LLM-readable documentation
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.
What is Streamfog?
Streamfog is a Windows desktop app (https://streamfog.com) that streamers use to put AR effects on their face during live broadcasts β face filters ("beauty smooth", "cyber helmet"), animated lenses, background effects, and Vtuber-style avatars. It takes your webcam feed, applies the effect in real time, and renders the result into OBS Studio through a browser source.
Two things matter for automation:
Streamfog has no public API, CLI, or plugin SDK. You cannot script it directly, and it cannot tell you which lens is active. It is effectively a black box that only listens to Streamer.bot.
Streamer.bot is the remote control. Streamer.bot is a free automation tool for streamers. Streamfog registers itself with Streamer.bot as an integration, and Streamer.bot exposes a local WebSocket server that accepts
DoActioncommands by name (e.g. fire the actionSetLens_BeautySmooth).
This project is the bridge between the two: it gives an AI assistant (or
the dashboard, or any script) a clean tool interface β streamfog_set_lens,
streamfog_clear_effects, streamfog_toggle_avatar, streamfog_status,
streamfog_list_lenses β and translates each call into a Streamer.bot
DoAction dispatch. Without this server you would have to open Streamer.bot
and click actions manually; with it, your agent becomes a stream producer.
β οΈ Fire-and-forget: Streamer.bot does not report whether an action succeeded, and Streamfog cannot be queried. A tool returning "success" means dispatched, not applied β confirm visually on the stream.
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 |
|
Related MCP server: obs-showrunner-mcp
How to use this server (3 steps)
Install the two external apps (one-time): Streamfog + Streamer.bot, enable Streamfog's integration inside Streamer.bot, and enable Streamer.bot's WebSocket server on port 8080. Full walkthrough: docs/ONBOARDING.md.
Map your lenses: create
lenses.jsonlinking human-readable lens names to the exact Streamer.bot action names that apply them (see Lens Map).Start and drive it:
start.ps1boots the backend + dashboard; then either connect your MCP client (Claude Desktop / Cursor / opencode) over stdio orhttp://127.0.0.1:10994/mcp, click lenses on the dashboard, or call the REST API from scripts. All three surface the same bridge.
Architecture
Plain English: your AI talks to this server, this server talks to Streamer.bot, Streamer.bot tells Streamfog what to render, and OBS shows the result. Every hop is local.
βββββββββββββββ MCP ββββββββββββββββββββ WebSocket ββββββββββββββββ
β LLM Agent β ββββββββββββββββ β streamfog-mcp β βββββββββββββββββ β Streamer.bot β
β (Claude, β ββββββββββββββββ β :10994 (FastMCP) β βββββββββββββββββ β :8080 β
β Gemini) β stdio / /mcp β :10995 (React) β DoAction JSON β β
βββββββββββββββ ββββββββββββββββββββ ββββββββ¬βββββββββ
β Native Hook
ββββββββΌβββββββββ
β Streamfog β
β Desktop App β
ββββββββ¬βββββββββ
β Browser Source
ββββββββΌβββββββββ
β OBS Studio β
βββββββββββββββββMCP tools (for AI agents): served over stdio or the streamable HTTP endpoint at
http://127.0.0.1:10994/mcp.REST API (for scripts + dashboard):
/api/*on the same port, backed by the same bridge instance.Dashboard (for humans): React SPA at
:10995β lens grid, status KPIs, chat, logs.
The MCP endpoint is served at http://127.0.0.1:10994/mcp (streamable HTTP)
in dual mode, alongside the REST API and dashboard.
Quick Start
uv sync
# Edit lenses.json with your Streamer.bot action names
# Set STREAMFOG_MCP_STREAMERBOT_TOKEN in .env if using auth
.\start.ps1MCP-only via stdio (for Cursor, Claude Desktop):
uv run -m streamfog_mcp --stdioPrerequisites
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.jsonpopulated with your actionβlens mappings
See docs/ONBOARDING.md for the step-by-step walkthrough.
Configuration
Variable | Default | Description |
|
| Streamer.bot WebSocket host |
|
| Streamer.bot WebSocket port |
| β | Streamer.bot auth token |
|
| Path to lensβaction mapping file |
|
| Backend port |
|
| Logging level |
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. Keys starting with _ are ignored; unknown identifiers fall back to the action SetLens_{identifier}.
MCP Tools (5)
Lens Control
Tool | Description |
| Activate a specific AR lens or face filter |
| Strip all effects, return camera to baseline |
| Toggle Vtuber-style avatar on/off |
Discovery β READ_ONLY
Tool | Description |
| List all configured lenses from lenses.json |
| Bridge connection health + lens count |
REST API
Endpoint | Method | Description |
| GET | Liveness probe (status, version, uptime, tool count, bridge) |
| GET | Server + bridge health |
| GET | List all lenses |
| POST | Activate a lens ( |
| POST | Reload lens map from disk |
| POST | Clear all effects |
| POST | Toggle avatar |
| GET | Dynamic MCP tool list with schemas |
| GET | Capability discovery |
| GET | Skill list |
| GET | Skill content (markdown) |
| GET | Local LLM provider probe (Ollama/LM Studio/vLLM) + GPU |
| GET | Ring-buffer log window |
| GET | Tool list, system info, errors |
Web Dashboard
Dark SOTA dashboard at :10995 (React + Vite + Tailwind + Zustand):
Dashboard β hero + KPI cards (server, tools, bridge, uptime), lens grid, quick actions, exponential-backoff health
Tools β dynamic tool list with schemas from
/api/toolsChat β skill-first local LLM chat (Ollama/LM Studio/vLLM), 4 personalities, localStorage history, export
Settings β backend health + LLM provider detection
Help β architecture, env reference, troubleshooting
Logs β live ring-buffer modal (Ctrl+L)
Keyboard: Ctrl+Scroll zoom, Ctrl+0 reset, Ctrl+L logs.
Project Structure
streamfog-mcp/
βββ src/streamfog_mcp/
β βββ _mcp.py FastMCP singleton + resources
β βββ server.py FastAPI gateway (REST + /mcp mount)
β βββ __main__.py CLI entry (--stdio / --serve)
β βββ config.py Pydantic settings (STREAMFOG_MCP_ prefix)
β βββ errors.py _error_response() with logger.exception
β βββ logging_ring.py Ring buffer for /api/logs
β βββ skills/streamfog/ SKILL.md (chat preprompt)
β βββ tools/core_tools.py 5 @mcp.tool() decorators
β βββ services/streamerbot.py Streamer.bot WebSocket client
βββ webapp/ Vite + React 19 + Tailwind + Zustand
βββ native/ Tauri 2.0 desktop wrapper
βββ lenses.json Lens β action mapping
βββ pyproject.toml / uv.lock
βββ start.ps1 / start.bat
βββ justfile
βββ tests/ 13 tests (units + endpoint + e2e)Verification
just lint # ruff
just test # pytest (coverage-gated)
uv run pyright src/ # types
cd webapp && bun run check && bun run biome:ci
cd webapp && bunx playwright test # e2eKnown 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
Available Tools
5 toolsstreamfog_clear_effectsA
Strip all active AR assets, face filters, and canvas overlays in Streamfog.
Returns the camera feed to a clean, unfiltered video baseline. Dispatches the 'ClearEffects' action to Streamer.bot.
Return Format
{"success": true, "message": "All effects cleared β camera returned to baseline", "data": {"action": "ClearEffects"}}
Examples
await streamfog_clear_effects()
Inputs: no named parameters. Returns: object
streamfog_list_lensesARead-only
List all available AR lenses and face filters from the local lenses.json mapping.
Returns all lens identifiers and their corresponding Streamer.bot action names. Use reload=true to force a re-read from disk if lenses.json was modified.
Return Format
{"success": true, "data": {"lenses": {"beauty_smooth": "SetLens_BeautySmooth", "cyber_helmet": "SetLens_CyberHelmet"}, "count": 2, "path": "lenses.json"}}
Examples
await streamfog_list_lenses() await streamfog_list_lenses(reload=True)
Inputs: reload. Returns: object
streamfog_set_lensA
Activate a specific AR lens or face filter in Streamfog.
Resolves the lens identifier against the local lenses.json mapping file and dispatches the corresponding action to Streamer.bot. Falls back to a constructed action name 'SetLens_{identifier}' if no mapping found.
Return Format
{"success": true, "message": "Action 'SetLens_CyberHelmet' dispatched", "data": {"action": "SetLens_CyberHelmet", "lens": "cyber_helmet"}}
Examples
await streamfog_set_lens("beauty_smooth") await streamfog_set_lens("cyber_helmet")
Inputs: lens_identifier (required). Returns: object
streamfog_statusARead-only
Check the connection status to Streamfog via the Streamer.bot bridge.
Returns bridge connectivity, loaded lens count, and any recent errors. Use this before attempting lens operations to verify the bridge is healthy.
Return Format
{"success": true, "data": {"connected": bool, "host": "127.0.0.1", "port": 8080, "lenses_loaded": 5, "connected_at": 1715000000.0, "last_error": null}}
Examples
await streamfog_status()
Inputs: no named parameters. Returns: object
streamfog_toggle_avatarA
Toggle the Vtuber-style avatar overlay on or off in Streamfog.
Dispatches the 'ToggleAvatar' action to Streamer.bot. If no avatar is currently active, this activates the default avatar lens. If an avatar is active, it deactivates it.
Return Format
{"success": true, "message": "Avatar toggled", "data": {"action": "ToggleAvatar"}}
Examples
await streamfog_toggle_avatar()
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 5 tools
Each tool targets a distinct operation: status checks connectivity, set_lens activates a specific lens, clear_effects removes all effects, toggle_avatar toggles the avatar overlay, and list_lenses enumerates available lenses. There is no functional overlap.
All tool names follow a consistent streamfog_verb_noun pattern using snake_case. Verbs are descriptive and uniform, making it easy to predict tool behavior from the name.
Five tools is well-scoped for an AR lens management server. Each tool serves a core function: status, set lens, clear effects, toggle avatar, and list lenses, without unnecessary duplication.
The tool set covers essential operations for managing AR lenses, including status checking, activation, clearing, avatar toggling, and listing. A minor gap is the lack of a tool to get the currently active lens or avatar state, though status provides bridge health.
Maintenance
Related MCP Connectors
Multistream relay control: check live status, switch destinations, manage teams, generate overlays.
Build, edit and place TikTok LIVE overlay widgets (alerts, goals, games) from your AI assistant.
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
AI image, video, voice and music generation over MCP, routed to Veo 3.1, Seedance 2.5 and more.
Related MCP Servers
- AlicenseBqualityBmaintenanceAI-powered stream and recording control for OBS Studio through the Model Context Protocol10028Apache 2.0
- AlicenseBqualityDmaintenanceMCP server enabling LLMs to control OBS Studio through high-level show and effect APIs.18MIT
- AlicenseBqualityCmaintenanceMCP server that gives AI assistants direct control over Streamlabs Desktop, enabling scene switching, source/audio management, and streaming/recording controls through natural language.59MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to control and automate OBS Studio via natural language, covering scenes, sources, audio, recording, streaming, transitions, filters, media playback, diagnostics, and multi-step workflows over the OBS WebSocket protocol.89MIT