obs-studio-mcp 0.1.0__tar.gz

obs_studio_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e '.[dev]'
+      - name: Lint
+        run: ruff check src tests
+      - name: Tests
+        run: pytest
+      - name: Forbidden terms check
+        env:
+          FORBIDDEN_TERMS: ${{ secrets.FORBIDDEN_TERMS }}
+        run: |
+          if [ -n "$FORBIDDEN_TERMS" ] && git grep -qiE "$FORBIDDEN_TERMS" -- . ; then
+            echo "::error::forbidden terms found in repository"
+            exit 1
+          fi
+      - name: Secret shape check
+        run: |
+          if git grep -nE '(password|refresh_token|client_secret)"?\s*[:=]\s*"[A-Za-z0-9_/-]{20,}' -- ':!tests' ; then
+            echo "::error::possible hardcoded credential"
+            exit 1
+          fi

obs_studio_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

obs_studio_mcp-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+docs/superpowers/
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/

obs_studio_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aaronckj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

obs_studio_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: obs-studio-mcp
+Version: 0.1.0
+Summary: MCP server for controlling OBS Studio over obs-websocket v5: scenes, sources, audio, streaming, recording, replay buffer, stats, and text overlays.
+Project-URL: Homepage, https://github.com/aaronckj/obs-studio-mcp
+Project-URL: Issues, https://github.com/aaronckj/obs-studio-mcp/issues
+Author: aaronckj
+License-Expression: MIT
+License-File: LICENSE
+Keywords: mcp,model-context-protocol,obs,obs-studio,obs-websocket,streaming
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.2
+Requires-Dist: obsws-python>=1.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# obs-studio-mcp
+
+An MCP (Model Context Protocol) server for controlling OBS Studio over
+**obs-websocket v5**: scenes, sources, audio, text overlays, streaming,
+recording, replay buffer, virtual camera, and performance stats.
+
+- Talks to the obs-websocket server built into OBS 28+ (Tools → WebSocket
+  Server Settings).
+- Every mutating tool accepts `dry_run=true` and returns a preview instead
+  of acting — useful guard rails when an agent drives your live stream.
+- No secrets in this repo or in your MCP client config.
+
+## Quick start
+
+1. In OBS: **Tools → WebSocket Server Settings** → enable, note the port
+   (default 4455) and password.
+2. Provide connection settings via environment:
+
+```bash
+export OBS_MCP_HOST=127.0.0.1     # default
+export OBS_MCP_PORT=4455          # default
+export OBS_MCP_PASSWORD=yourpass  # via the default env backend
+```
+
+3. Add to your MCP client:
+
+```bash
+# Claude Code
+claude mcp add obs -s user -- uvx obs-studio-mcp
+```
+
+## Tools
+
+| Area | Tools |
+|---|---|
+| Scenes | `list_scenes`, `switch_scene`, `set_preview_scene`, `trigger_transition`, `set_studio_mode`, `list_scene_items`, `set_scene_item_visibility` |
+| Sources | `list_inputs`, `get_audio_levels`, `set_mute`, `set_volume`, `update_text_source`, `screenshot_source`, `media_control` |
+| Output | `stream_status`, `start_stream`, `stop_stream`, `record_status`, `start_record`, `stop_record`, `pause_record`, `save_replay`, `set_replay_buffer`, `set_virtual_cam` |
+| System | `get_stats`, `list_profiles`, `switch_profile`, `list_scene_collections`, `switch_scene_collection`, `trigger_hotkey`, `health_check` |
+
+`update_text_source` is handy for driving on-stream overlays from an agent —
+question-of-the-day, now-playing, countdowns — anything rendered by a Text
+source.
+
+## Secret storage
+
+The only secret is the websocket password.
+
+| Backend | Select with | Reads |
+|---|---|---|
+| `env` (default) | — | `OBS_MCP_PASSWORD` |
+| `file` | `OBS_MCP_SECRETS=file` | `~/.config/obs-studio-mcp/credentials.json` (0600) |
+| `vaultproxy` | `OBS_MCP_SECRETS=vaultproxy` (+ `VAULTPROXY_URL`) | a Vaultwarden vault via a local vaultproxy HTTP API |
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+ruff check src tests && pytest
+```
+
+Tests are fully offline (fake obs-websocket client).
+
+## License
+
+MIT

obs_studio_mcp-0.1.0/README.md

@@ -0,0 +1,66 @@
+# obs-studio-mcp
+
+An MCP (Model Context Protocol) server for controlling OBS Studio over
+**obs-websocket v5**: scenes, sources, audio, text overlays, streaming,
+recording, replay buffer, virtual camera, and performance stats.
+
+- Talks to the obs-websocket server built into OBS 28+ (Tools → WebSocket
+  Server Settings).
+- Every mutating tool accepts `dry_run=true` and returns a preview instead
+  of acting — useful guard rails when an agent drives your live stream.
+- No secrets in this repo or in your MCP client config.
+
+## Quick start
+
+1. In OBS: **Tools → WebSocket Server Settings** → enable, note the port
+   (default 4455) and password.
+2. Provide connection settings via environment:
+
+```bash
+export OBS_MCP_HOST=127.0.0.1     # default
+export OBS_MCP_PORT=4455          # default
+export OBS_MCP_PASSWORD=yourpass  # via the default env backend
+```
+
+3. Add to your MCP client:
+
+```bash
+# Claude Code
+claude mcp add obs -s user -- uvx obs-studio-mcp
+```
+
+## Tools
+
+| Area | Tools |
+|---|---|
+| Scenes | `list_scenes`, `switch_scene`, `set_preview_scene`, `trigger_transition`, `set_studio_mode`, `list_scene_items`, `set_scene_item_visibility` |
+| Sources | `list_inputs`, `get_audio_levels`, `set_mute`, `set_volume`, `update_text_source`, `screenshot_source`, `media_control` |
+| Output | `stream_status`, `start_stream`, `stop_stream`, `record_status`, `start_record`, `stop_record`, `pause_record`, `save_replay`, `set_replay_buffer`, `set_virtual_cam` |
+| System | `get_stats`, `list_profiles`, `switch_profile`, `list_scene_collections`, `switch_scene_collection`, `trigger_hotkey`, `health_check` |
+
+`update_text_source` is handy for driving on-stream overlays from an agent —
+question-of-the-day, now-playing, countdowns — anything rendered by a Text
+source.
+
+## Secret storage
+
+The only secret is the websocket password.
+
+| Backend | Select with | Reads |
+|---|---|---|
+| `env` (default) | — | `OBS_MCP_PASSWORD` |
+| `file` | `OBS_MCP_SECRETS=file` | `~/.config/obs-studio-mcp/credentials.json` (0600) |
+| `vaultproxy` | `OBS_MCP_SECRETS=vaultproxy` (+ `VAULTPROXY_URL`) | a Vaultwarden vault via a local vaultproxy HTTP API |
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+ruff check src tests && pytest
+```
+
+Tests are fully offline (fake obs-websocket client).
+
+## License
+
+MIT

obs_studio_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "obs-studio-mcp"
+version = "0.1.0"
+description = "MCP server for controlling OBS Studio over obs-websocket v5: scenes, sources, audio, streaming, recording, replay buffer, stats, and text overlays."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "aaronckj" }]
+keywords = ["mcp", "obs", "obs-studio", "obs-websocket", "streaming", "model-context-protocol"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "mcp>=1.2",
+  "obsws-python>=1.7",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+obs-studio-mcp = "obs_studio_mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/aaronckj/obs-studio-mcp"
+Issues = "https://github.com/aaronckj/obs-studio-mcp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/obs_studio_mcp"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

obs_studio_mcp-0.1.0/src/obs_studio_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

obs_studio_mcp-0.1.0/src/obs_studio_mcp/__main__.py

@@ -0,0 +1,13 @@
+"""CLI entry: run the MCP server."""
+
+from __future__ import annotations
+
+
+def main() -> None:
+    from .server import build_app
+
+    build_app().run()
+
+
+if __name__ == "__main__":
+    main()

obs_studio_mcp-0.1.0/src/obs_studio_mcp/client.py

@@ -0,0 +1,72 @@
+"""obs-websocket v5 connection wrapper."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+logger = logging.getLogger("obs_studio_mcp")
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+
+
+class ObsError(RuntimeError):
+    pass
+
+
+class OBS:
+    """Lazy holder for an obsws-python ReqClient (injectable for tests)."""
+
+    def __init__(self, client: Any = None):
+        self._client = client
+
+    @property
+    def client(self) -> Any:
+        if self._client is None:
+            import obsws_python as obs
+
+            from .secrets import get_store
+
+            host = os.environ.get("OBS_MCP_HOST", "127.0.0.1")
+            port = int(os.environ.get("OBS_MCP_PORT", "4455"))
+            password = get_store().get("password") or ""
+            try:
+                self._client = obs.ReqClient(
+                    host=host, port=port, password=password, timeout=5
+                )
+            except Exception as exc:
+                raise ObsError(
+                    f"cannot connect to OBS websocket at {host}:{port} — is OBS running "
+                    "with obs-websocket enabled (Tools → WebSocket Server Settings)? "
+                    f"({exc})"
+                ) from exc
+        return self._client
+
+    def call(self, method: str, *args: Any, **kwargs: Any) -> Any:
+        try:
+            result = getattr(self.client, method)(*args, **kwargs)
+            logger.info("obs %s ok", method)
+            return result
+        except ObsError:
+            raise
+        except Exception as exc:
+            logger.error("obs %s failed: %s", method, exc)
+            raise ObsError(f"{method} failed: {exc}") from exc
+
+
+def preview(action: str, would: dict) -> dict:
+    return {"preview": True, "action": action, "would": would}
+
+
+_obs: OBS | None = None
+
+
+def get_obs() -> OBS:
+    global _obs
+    if _obs is None:
+        _obs = OBS()
+    return _obs

obs_studio_mcp-0.1.0/src/obs_studio_mcp/secrets.py

@@ -0,0 +1,96 @@
+"""Pluggable secret storage for the OBS websocket password.
+
+Selected via OBS_MCP_SECRETS (file | env | vaultproxy, default env→file):
+the websocket password is the only secret this server ever needs.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+DEFAULT_PATH = Path.home() / ".config" / "obs-studio-mcp" / "credentials.json"
+
+
+class SecretStore:
+    def get(self, key: str) -> str | None:
+        raise NotImplementedError
+
+    def set(self, key: str, value: str) -> None:
+        raise NotImplementedError
+
+
+class FileStore(SecretStore):
+    def __init__(self, path: Path | None = None):
+        self.path = Path(path or DEFAULT_PATH)
+
+    def _load(self) -> dict:
+        if not self.path.exists():
+            return {}
+        return json.loads(self.path.read_text())
+
+    def get(self, key: str) -> str | None:
+        return self._load().get(key)
+
+    def set(self, key: str, value: str) -> None:
+        data = self._load()
+        data[key] = value
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(json.dumps(data, indent=2))
+        self.path.chmod(0o600)
+
+
+class EnvStore(SecretStore):
+    def get(self, key: str) -> str | None:
+        return os.environ.get(f"OBS_MCP_{key.upper()}")
+
+    def set(self, key: str, value: str) -> None:
+        raise NotImplementedError("env secret backend is read-only")
+
+
+class VaultproxyStore(SecretStore):
+    def __init__(self, base_url: str | None = None):
+        self.base_url = (
+            base_url or os.environ.get("VAULTPROXY_URL", "http://127.0.0.1:8199")
+        ).rstrip("/")
+
+    def _request(self, method: str, key: str, body: dict | None = None) -> dict:
+        req = Request(
+            f"{self.base_url}/items/obs-studio-mcp%2F{key}",
+            method=method,
+            data=json.dumps(body).encode() if body is not None else None,
+            headers={"content-type": "application/json"},
+        )
+        try:
+            with urlopen(req, timeout=10) as resp:
+                raw = resp.read()
+        except URLError as exc:
+            raise RuntimeError(
+                f"vaultproxy unreachable at {self.base_url}: {exc.reason}"
+            ) from exc
+        return json.loads(raw) if raw else {}
+
+    def get(self, key: str) -> str | None:
+        try:
+            return self._request("GET", key).get("value")
+        except RuntimeError:
+            raise
+        except Exception:
+            return None
+
+    def set(self, key: str, value: str) -> None:
+        self._request("PUT", key, {"value": value})
+
+
+def get_store() -> SecretStore:
+    backend = os.environ.get("OBS_MCP_SECRETS", "env")
+    if backend == "file":
+        return FileStore()
+    if backend == "env":
+        return EnvStore()
+    if backend == "vaultproxy":
+        return VaultproxyStore()
+    raise ValueError(f"unknown OBS_MCP_SECRETS backend: {backend!r} (file|env|vaultproxy)")

obs_studio_mcp-0.1.0/src/obs_studio_mcp/server.py

@@ -0,0 +1,22 @@
+"""FastMCP app assembly."""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from .tools import filters, output, scenes, sources, system
+
+
+def build_app() -> FastMCP:
+    mcp = FastMCP(
+        "obs-studio",
+        instructions=(
+            "Control a local OBS Studio over obs-websocket v5: scenes, sources, "
+            "audio, text overlays, streaming, recording, replay buffer, virtual "
+            "camera, and performance stats. Every mutating tool accepts "
+            "dry_run=True to preview without acting."
+        ),
+    )
+    for module in (scenes, sources, filters, output, system):
+        module.register(mcp)
+    return mcp

obs_studio_mcp-0.1.0/src/obs_studio_mcp/tools/filters.py

@@ -0,0 +1,140 @@
+"""Source filter and scene-item transform tools, plus a stream health sampler."""
+
+from __future__ import annotations
+
+import time
+
+from ..client import get_obs, preview
+
+
+def summarize_health(samples: list[dict]) -> dict:
+    """Aggregate stat samples into a verdict (pure logic, unit-tested)."""
+    if not samples:
+        return {"verdict": "no samples"}
+    n = len(samples)
+    avg_fps = sum(s["fps"] for s in samples) / n
+    cpu = sum(s["cpu"] for s in samples) / n
+    render_dropped = samples[-1]["render_skipped"] - samples[0]["render_skipped"]
+    output_dropped = samples[-1]["output_skipped"] - samples[0]["output_skipped"]
+    frames = samples[-1].get("output_total", 0) - samples[0].get("output_total", 0)
+    drop_pct = (output_dropped / frames * 100) if frames else 0.0
+    issues = []
+    if drop_pct > 1.0:
+        issues.append(f"network/encoding drops {drop_pct:.1f}% (check bitrate/encoder)")
+    if render_dropped > n:
+        issues.append(f"renderer missed {render_dropped} frames (GPU overload)")
+    if cpu > 80:
+        issues.append(f"CPU {cpu:.0f}% (encoder overload risk)")
+    return {
+        "samples": n,
+        "avg_fps": round(avg_fps, 1),
+        "avg_cpu_percent": round(cpu, 1),
+        "render_frames_missed": render_dropped,
+        "output_frames_dropped": output_dropped,
+        "drop_percent": round(drop_pct, 2),
+        "verdict": "healthy" if not issues else "; ".join(issues),
+    }
+
+
+def register(mcp) -> None:
+    @mcp.tool()
+    def list_source_filters(source: str) -> list[dict]:
+        """List filters on a source with enabled state."""
+        obs = get_obs()
+        res = obs.call("get_source_filter_list", source)
+        return [
+            {
+                "name": f["filterName"],
+                "kind": f["filterKind"],
+                "enabled": f["filterEnabled"],
+            }
+            for f in res.filters
+        ]
+
+    @mcp.tool()
+    def set_filter_enabled(
+        source: str, filter_name: str, enabled: bool, dry_run: bool = False
+    ) -> dict:
+        """Enable or disable a named filter on a source."""
+        if dry_run:
+            return preview(
+                "set_filter_enabled",
+                {"source": source, "filter": filter_name, "enabled": enabled},
+            )
+        obs = get_obs()
+        obs.call("set_source_filter_enabled", source, filter_name, enabled)
+        return {"source": source, "filter": filter_name, "enabled": enabled}
+
+    @mcp.tool()
+    def get_scene_item_transform(scene: str, item_id: int) -> dict:
+        """Get a scene item's position, scale, and crop."""
+        obs = get_obs()
+        res = obs.call("get_scene_item_transform", scene, item_id)
+        t = res.scene_item_transform
+        return {
+            "x": t.get("positionX"),
+            "y": t.get("positionY"),
+            "scale_x": t.get("scaleX"),
+            "scale_y": t.get("scaleY"),
+            "width": t.get("width"),
+            "height": t.get("height"),
+        }
+
+    @mcp.tool()
+    def set_scene_item_transform(
+        scene: str,
+        item_id: int,
+        x: float | None = None,
+        y: float | None = None,
+        scale_x: float | None = None,
+        scale_y: float | None = None,
+        dry_run: bool = False,
+    ) -> dict:
+        """Move/scale a scene item (item_id from list_scene_items). Only supplied
+        fields change — e.g. scale_x/scale_y 0.5 halves a facecam."""
+        changes: dict = {}
+        if x is not None:
+            changes["positionX"] = x
+        if y is not None:
+            changes["positionY"] = y
+        if scale_x is not None:
+            changes["scaleX"] = scale_x
+        if scale_y is not None:
+            changes["scaleY"] = scale_y
+        if not changes:
+            return {"error": "provide at least one of x, y, scale_x, scale_y"}
+        if dry_run:
+            return preview(
+                "set_scene_item_transform",
+                {"scene": scene, "item_id": item_id, **changes},
+            )
+        obs = get_obs()
+        obs.call("set_scene_item_transform", scene, item_id, changes)
+        return {"scene": scene, "item_id": item_id, "applied": changes}
+
+    @mcp.tool()
+    def watch_health(seconds: int = 10) -> dict:
+        """Sample OBS stats for up to 60 seconds and report a stream-health
+        verdict: dropped-frame %, GPU misses, CPU pressure."""
+        seconds = max(2, min(60, seconds))
+        obs = get_obs()
+        samples = []
+        for _ in range(seconds):
+            s = obs.call("get_stats")
+            sample = {
+                "fps": s.active_fps,
+                "cpu": s.cpu_usage,
+                "render_skipped": s.render_skipped_frames,
+                "output_skipped": s.output_skipped_frames,
+            }
+            try:
+                stream = obs.call("get_stream_status")
+                sample["output_total"] = getattr(stream, "output_total_frames", 0)
+                sample["output_skipped"] = getattr(
+                    stream, "output_skipped_frames", sample["output_skipped"]
+                )
+            except Exception:  # noqa: BLE001 - not streaming; stats-only sample
+                sample["output_total"] = 0
+            samples.append(sample)
+            time.sleep(1)
+        return summarize_health(samples)

obs_studio_mcp-0.1.0/src/obs_studio_mcp/tools/output.py

@@ -0,0 +1,104 @@
+"""Streaming, recording, replay buffer, and virtual camera tools."""
+
+from __future__ import annotations
+
+from ..client import get_obs, preview
+
+
+def register(mcp) -> None:
+    @mcp.tool()
+    def stream_status() -> dict:
+        """Streaming state: live, duration, bytes, dropped frames."""
+        obs = get_obs()
+        s = obs.call("get_stream_status")
+        return {
+            "streaming": s.output_active,
+            "reconnecting": getattr(s, "output_reconnecting", False),
+            "duration_ms": getattr(s, "output_duration", 0),
+            "total_frames": getattr(s, "output_total_frames", 0),
+            "skipped_frames": getattr(s, "output_skipped_frames", 0),
+        }
+
+    @mcp.tool()
+    def start_stream(dry_run: bool = False) -> dict:
+        """Go live: start streaming to the configured service."""
+        if dry_run:
+            return preview("start_stream", {"note": "starts the live broadcast"})
+        obs = get_obs()
+        obs.call("start_stream")
+        return {"streaming": True}
+
+    @mcp.tool()
+    def stop_stream(dry_run: bool = False) -> dict:
+        """End the live stream."""
+        if dry_run:
+            return preview("stop_stream", {"note": "ends the live broadcast"})
+        obs = get_obs()
+        obs.call("stop_stream")
+        return {"streaming": False}
+
+    @mcp.tool()
+    def record_status() -> dict:
+        """Recording state: active, paused, duration, output path."""
+        obs = get_obs()
+        r = obs.call("get_record_status")
+        return {
+            "recording": r.output_active,
+            "paused": getattr(r, "output_paused", False),
+            "duration_ms": getattr(r, "output_duration", 0),
+        }
+
+    @mcp.tool()
+    def start_record(dry_run: bool = False) -> dict:
+        """Start recording."""
+        if dry_run:
+            return preview("start_record", {})
+        obs = get_obs()
+        obs.call("start_record")
+        return {"recording": True}
+
+    @mcp.tool()
+    def stop_record(dry_run: bool = False) -> dict:
+        """Stop recording; returns the saved file path."""
+        if dry_run:
+            return preview("stop_record", {})
+        obs = get_obs()
+        res = obs.call("stop_record")
+        return {"recording": False, "output_path": getattr(res, "output_path", None)}
+
+    @mcp.tool()
+    def pause_record(paused: bool, dry_run: bool = False) -> dict:
+        """Pause (true) or resume (false) the recording."""
+        if dry_run:
+            return preview("pause_record", {"paused": paused})
+        obs = get_obs()
+        obs.call("pause_record" if paused else "resume_record")
+        return {"paused": paused}
+
+    @mcp.tool()
+    def save_replay(dry_run: bool = False) -> dict:
+        """Save the replay buffer (must be running). Returns the clip path."""
+        if dry_run:
+            return preview("save_replay", {})
+        obs = get_obs()
+        obs.call("save_replay_buffer")
+        res = obs.call("get_last_replay_buffer_replay")
+        return {"saved": getattr(res, "saved_replay_path", None)}
+
+    @mcp.tool()
+    def set_replay_buffer(active: bool, dry_run: bool = False) -> dict:
+        """Start (true) or stop (false) the replay buffer."""
+        if dry_run:
+            return preview("set_replay_buffer", {"active": active})
+        obs = get_obs()
+        obs.call("start_replay_buffer" if active else "stop_replay_buffer")
+        return {"replay_buffer": active}
+
+    @mcp.tool()
+    def set_virtual_cam(active: bool, dry_run: bool = False) -> dict:
+        """Start (true) or stop (false) the virtual camera."""
+        if dry_run:
+            return preview("set_virtual_cam", {"active": active})
+        obs = get_obs()
+        obs.call("start_virtual_cam" if active else "stop_virtual_cam")
+        return {"virtual_cam": active}

obs_studio_mcp-0.1.0/src/obs_studio_mcp/tools/scenes.py

@@ -0,0 +1,82 @@
+"""Scene and transition tools."""
+
+from __future__ import annotations
+
+from ..client import get_obs, preview
+
+
+def register(mcp) -> None:
+    @mcp.tool()
+    def list_scenes() -> dict:
+        """List scenes and the current program/preview scene."""
+        obs = get_obs()
+        res = obs.call("get_scene_list")
+        return {
+            "current_program": res.current_program_scene_name,
+            "current_preview": getattr(res, "current_preview_scene_name", None),
+            "scenes": [s["sceneName"] for s in reversed(res.scenes)],
+        }
+
+    @mcp.tool()
+    def switch_scene(scene: str, dry_run: bool = False) -> dict:
+        """Switch the program output to a scene (immediate cut on program)."""
+        if dry_run:
+            return preview("switch_scene", {"scene": scene})
+        obs = get_obs()
+        obs.call("set_current_program_scene", scene)
+        return {"program_scene": scene}
+
+    @mcp.tool()
+    def set_preview_scene(scene: str, dry_run: bool = False) -> dict:
+        """Set the preview scene (studio mode)."""
+        if dry_run:
+            return preview("set_preview_scene", {"scene": scene})
+        obs = get_obs()
+        obs.call("set_current_preview_scene", scene)
+        return {"preview_scene": scene}
+
+    @mcp.tool()
+    def trigger_transition(dry_run: bool = False) -> dict:
+        """Trigger the studio-mode transition (preview → program)."""
+        if dry_run:
+            return preview("trigger_transition", {})
+        obs = get_obs()
+        obs.call("trigger_studio_mode_transition")
+        return {"transitioned": True}
+
+    @mcp.tool()
+    def set_studio_mode(enabled: bool, dry_run: bool = False) -> dict:
+        """Enable or disable studio mode."""
+        if dry_run:
+            return preview("set_studio_mode", {"enabled": enabled})
+        obs = get_obs()
+        obs.call("set_studio_mode_enabled", enabled)
+        return {"studio_mode": enabled}
+
+    @mcp.tool()
+    def list_scene_items(scene: str) -> list[dict]:
+        """List the items (sources) inside a scene with visibility state."""
+        obs = get_obs()
+        res = obs.call("get_scene_item_list", scene)
+        return [
+            {
+                "id": i["sceneItemId"],
+                "source": i["sourceName"],
+                "visible": i["sceneItemEnabled"],
+            }
+            for i in res.scene_items
+        ]
+
+    @mcp.tool()
+    def set_scene_item_visibility(
+        scene: str, item_id: int, visible: bool, dry_run: bool = False
+    ) -> dict:
+        """Show or hide a scene item (item_id from list_scene_items)."""
+        if dry_run:
+            return preview(
+                "set_scene_item_visibility",
+                {"scene": scene, "item_id": item_id, "visible": visible},
+            )
+        obs = get_obs()
+        obs.call("set_scene_item_enabled", scene, item_id, visible)
+        return {"scene": scene, "item_id": item_id, "visible": visible}

obs_studio_mcp-0.1.0/src/obs_studio_mcp/tools/sources.py

@@ -0,0 +1,104 @@
+"""Input/source tools: audio, text overlays, media, screenshots."""
+
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+
+from ..client import get_obs, preview
+
+
+def register(mcp) -> None:
+    @mcp.tool()
+    def list_inputs() -> list[dict]:
+        """List all inputs (sources) with their kinds."""
+        obs = get_obs()
+        res = obs.call("get_input_list")
+        return [
+            {"name": i["inputName"], "kind": i["inputKind"]} for i in res.inputs
+        ]
+
+    @mcp.tool()
+    def get_audio_levels() -> list[dict]:
+        """List audio inputs with mute state and volume (dB)."""
+        obs = get_obs()
+        inputs = obs.call("get_input_list").inputs
+        out = []
+        for i in inputs:
+            name = i["inputName"]
+            try:
+                mute = obs.call("get_input_mute", name).input_muted
+                vol = obs.call("get_input_volume", name)
+                out.append(
+                    {
+                        "name": name,
+                        "muted": mute,
+                        "volume_db": round(vol.input_volume_db, 1),
+                    }
+                )
+            except Exception:  # noqa: BLE001 - non-audio inputs raise; skip them
+                continue
+        return out
+
+    @mcp.tool()
+    def set_mute(input_name: str, muted: bool, dry_run: bool = False) -> dict:
+        """Mute or unmute an audio input."""
+        if dry_run:
+            return preview("set_mute", {"input": input_name, "muted": muted})
+        obs = get_obs()
+        obs.call("set_input_mute", input_name, muted)
+        return {"input": input_name, "muted": muted}
+
+    @mcp.tool()
+    def set_volume(input_name: str, volume_db: float, dry_run: bool = False) -> dict:
+        """Set an audio input's volume in dB (0 = unity, negative = quieter)."""
+        if dry_run:
+            return preview("set_volume", {"input": input_name, "volume_db": volume_db})
+        obs = get_obs()
+        obs.call("set_input_volume", input_name, vol_db=volume_db)
+        return {"input": input_name, "volume_db": volume_db}
+
+    @mcp.tool()
+    def update_text_source(input_name: str, text: str, dry_run: bool = False) -> dict:
+        """Set the text of a Text (GDI+/FreeType) source — e.g. an on-stream overlay
+        line like a giveaway question or now-playing label."""
+        if dry_run:
+            return preview("update_text_source", {"input": input_name, "text": text})
+        obs = get_obs()
+        obs.call("set_input_settings", input_name, {"text": text}, True)
+        return {"input": input_name, "text": text}
+
+    @mcp.tool()
+    def screenshot_source(
+        source: str, file_path: str, width: int | None = None, dry_run: bool = False
+    ) -> dict:
+        """Save a PNG screenshot of a source (or scene) to a local file."""
+        if dry_run:
+            return preview("screenshot_source", {"source": source, "file_path": file_path})
+        obs = get_obs()
+        kwargs = {"name": source, "img_format": "png", "quality": -1}
+        if width:
+            kwargs["width"] = width
+        res = obs.call("get_source_screenshot", **kwargs)
+        data = res.image_data.split(",", 1)[-1]
+        Path(file_path).write_bytes(base64.b64decode(data))
+        return {"saved": file_path, "source": source}
+
+    @mcp.tool()
+    def media_control(input_name: str, action: str, dry_run: bool = False) -> dict:
+        """Control a media source. action: play|pause|restart|stop|next|previous."""
+        actions = {
+            "play": "OBS_WEBSOCKET_MEDIA_INPUT_ACTION_PLAY",
+            "pause": "OBS_WEBSOCKET_MEDIA_INPUT_ACTION_PAUSE",
+            "restart": "OBS_WEBSOCKET_MEDIA_INPUT_ACTION_RESTART",
+            "stop": "OBS_WEBSOCKET_MEDIA_INPUT_ACTION_STOP",
+            "next": "OBS_WEBSOCKET_MEDIA_INPUT_ACTION_NEXT",
+            "previous": "OBS_WEBSOCKET_MEDIA_INPUT_ACTION_PREVIOUS",
+        }
+        if action not in actions:
+            return {"error": f"action must be one of {sorted(actions)}"}
+        if dry_run:
+            return preview("media_control", {"input": input_name, "action": action})
+        obs = get_obs()
+        obs.call("trigger_media_input_action", input_name, actions[action])
+        return {"input": input_name, "action": action}

obs_studio_mcp-0.1.0/src/obs_studio_mcp/tools/system.py

@@ -0,0 +1,80 @@
+"""System tools: stats, profiles, scene collections, hotkeys, health."""
+
+from __future__ import annotations
+
+from ..client import get_obs, preview
+
+
+def register(mcp) -> None:
+    @mcp.tool()
+    def get_stats() -> dict:
+        """OBS performance stats: CPU, memory, FPS, frame drops, disk space."""
+        obs = get_obs()
+        s = obs.call("get_stats")
+        return {
+            "cpu_percent": round(s.cpu_usage, 1),
+            "memory_mb": round(s.memory_usage, 1),
+            "fps": round(s.active_fps, 2),
+            "render_missed_frames": s.render_skipped_frames,
+            "output_skipped_frames": s.output_skipped_frames,
+            "free_disk_mb": round(s.available_disk_space, 0),
+        }
+
+    @mcp.tool()
+    def list_profiles() -> dict:
+        """List OBS profiles and the current one."""
+        obs = get_obs()
+        res = obs.call("get_profile_list")
+        return {"current": res.current_profile_name, "profiles": res.profiles}
+
+    @mcp.tool()
+    def switch_profile(profile: str, dry_run: bool = False) -> dict:
+        """Switch OBS profile (stream settings bundle)."""
+        if dry_run:
+            return preview("switch_profile", {"profile": profile})
+        obs = get_obs()
+        obs.call("set_current_profile", profile)
+        return {"profile": profile}
+
+    @mcp.tool()
+    def list_scene_collections() -> dict:
+        """List scene collections and the current one."""
+        obs = get_obs()
+        res = obs.call("get_scene_collection_list")
+        return {
+            "current": res.current_scene_collection_name,
+            "collections": res.scene_collections,
+        }
+
+    @mcp.tool()
+    def switch_scene_collection(name: str, dry_run: bool = False) -> dict:
+        """Switch scene collection (full scene layout bundle)."""
+        if dry_run:
+            return preview("switch_scene_collection", {"name": name})
+        obs = get_obs()
+        obs.call("set_current_scene_collection", name)
+        return {"scene_collection": name}
+
+    @mcp.tool()
+    def trigger_hotkey(hotkey_name: str, dry_run: bool = False) -> dict:
+        """Trigger an OBS hotkey by name (see get_hotkey_list in OBS docs)."""
+        if dry_run:
+            return preview("trigger_hotkey", {"hotkey_name": hotkey_name})
+        obs = get_obs()
+        obs.call("trigger_hot_key_by_name", hotkey_name)
+        return {"triggered": hotkey_name}
+
+    @mcp.tool()
+    def health_check() -> dict:
+        """Verify the OBS websocket connection and report versions."""
+        try:
+            obs = get_obs()
+            v = obs.call("get_version")
+            return {
+                "status": "ok",
+                "obs_version": v.obs_version,
+                "websocket_version": v.obs_web_socket_version,
+                "platform": v.platform,
+            }
+        except Exception as exc:  # noqa: BLE001 - health check reports, never raises
+            return {"status": f"error: {exc}"}

obs_studio_mcp-0.1.0/tests/test_health.py

@@ -0,0 +1,43 @@
+from obs_studio_mcp.tools.filters import summarize_health
+
+
+def sample(fps=60.0, cpu=20.0, render=0, out_skipped=0, out_total=0):
+    return {
+        "fps": fps,
+        "cpu": cpu,
+        "render_skipped": render,
+        "output_skipped": out_skipped,
+        "output_total": out_total,
+    }
+
+
+def test_healthy_stream():
+    samples = [sample(out_total=i * 60) for i in range(10)]
+    out = summarize_health(samples)
+    assert out["verdict"] == "healthy"
+    assert out["avg_fps"] == 60.0
+
+
+def test_network_drops_flagged():
+    samples = [
+        sample(out_skipped=i * 5, out_total=i * 60) for i in range(10)
+    ]
+    out = summarize_health(samples)
+    assert "drops" in out["verdict"]
+    assert out["drop_percent"] > 1.0
+
+
+def test_gpu_overload_flagged():
+    samples = [sample(render=i * 10, out_total=i * 60) for i in range(10)]
+    out = summarize_health(samples)
+    assert "GPU" in out["verdict"]
+
+
+def test_cpu_pressure_flagged():
+    samples = [sample(cpu=95.0, out_total=i * 60) for i in range(10)]
+    out = summarize_health(samples)
+    assert "CPU" in out["verdict"]
+
+
+def test_empty_samples():
+    assert summarize_health([])["verdict"] == "no samples"

obs_studio_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,28 @@
+import asyncio
+
+from obs_studio_mcp.server import build_app
+
+EXPECTED = {
+    # scenes
+    "list_scenes", "switch_scene", "set_preview_scene", "trigger_transition",
+    "set_studio_mode", "list_scene_items", "set_scene_item_visibility",
+    # sources
+    "list_inputs", "get_audio_levels", "set_mute", "set_volume",
+    "update_text_source", "screenshot_source", "media_control",
+    # output
+    "stream_status", "start_stream", "stop_stream", "record_status",
+    "start_record", "stop_record", "pause_record", "save_replay",
+    "set_replay_buffer", "set_virtual_cam",
+    # filters/transforms/health
+    "list_source_filters", "set_filter_enabled", "get_scene_item_transform",
+    "set_scene_item_transform", "watch_health",
+    # system
+    "get_stats", "list_profiles", "switch_profile", "list_scene_collections",
+    "switch_scene_collection", "trigger_hotkey", "health_check",
+}
+
+
+def test_all_tools_registered():
+    app = build_app()
+    tools = asyncio.run(app.list_tools())
+    assert {t.name for t in tools} == EXPECTED

obs_studio_mcp-0.1.0/tests/test_tools.py

@@ -0,0 +1,100 @@
+import asyncio
+import json
+from types import SimpleNamespace
+
+import obs_studio_mcp.client as client_mod
+from obs_studio_mcp.client import OBS
+from obs_studio_mcp.server import build_app
+
+
+class FakeReqClient:
+    """Records calls; returns canned obsws-style responses."""
+
+    def __init__(self):
+        self.calls = []
+
+    def _record(self, name, *args, **kwargs):
+        self.calls.append((name, args, kwargs))
+
+    def get_scene_list(self):
+        self._record("get_scene_list")
+        return SimpleNamespace(
+            current_program_scene_name="Game",
+            current_preview_scene_name="BRB",
+            scenes=[{"sceneName": "BRB"}, {"sceneName": "Game"}],
+        )
+
+    def set_current_program_scene(self, scene):
+        self._record("set_current_program_scene", scene)
+
+    def get_stream_status(self):
+        self._record("get_stream_status")
+        return SimpleNamespace(
+            output_active=True,
+            output_reconnecting=False,
+            output_duration=61000,
+            output_total_frames=3660,
+            output_skipped_frames=2,
+        )
+
+    def set_input_mute(self, name, muted):
+        self._record("set_input_mute", name, muted)
+
+    def set_input_settings(self, name, settings, overlay):
+        self._record("set_input_settings", name, settings, overlay)
+
+
+def call_tool(app, name, args=None):
+    result = asyncio.run(app.call_tool(name, args or {}))
+    # FastMCP returns a list of content blocks; first is the JSON text.
+    blocks = result[0] if isinstance(result, tuple) else result
+    return json.loads(blocks[0].text)
+
+
+def make_app(fake):
+    client_mod._obs = OBS(client=fake)
+    return build_app()
+
+
+def teardown_function():
+    client_mod._obs = None
+
+
+def test_list_scenes_shapes_response():
+    fake = FakeReqClient()
+    app = make_app(fake)
+    out = call_tool(app, "list_scenes")
+    assert out["current_program"] == "Game"
+    assert out["scenes"] == ["Game", "BRB"]
+
+
+def test_switch_scene_calls_client():
+    fake = FakeReqClient()
+    app = make_app(fake)
+    out = call_tool(app, "switch_scene", {"scene": "BRB"})
+    assert out == {"program_scene": "BRB"}
+    assert ("set_current_program_scene", ("BRB",), {}) in fake.calls
+
+
+def test_switch_scene_dry_run_does_not_call():
+    fake = FakeReqClient()
+    app = make_app(fake)
+    out = call_tool(app, "switch_scene", {"scene": "BRB", "dry_run": True})
+    assert out["preview"] is True
+    assert fake.calls == []
+
+
+def test_stream_status_shapes_response():
+    fake = FakeReqClient()
+    app = make_app(fake)
+    out = call_tool(app, "stream_status")
+    assert out["streaming"] is True
+    assert out["skipped_frames"] == 2
+
+
+def test_update_text_source():
+    fake = FakeReqClient()
+    app = make_app(fake)
+    out = call_tool(app, "update_text_source", {"input_name": "Question", "text": "Q: fave boss?"})
+    assert out["text"] == "Q: fave boss?"
+    assert ("set_input_settings", ("Question", {"text": "Q: fave boss?"}, True), {}) in fake.calls