obs-mcp 0.2.0__py3-none-any.whl

obs_mcp/error_codes.py

@@ -0,0 +1,25 @@
+from enum import IntEnum
+
+
+class ErrorCode(IntEnum):
+    # Connection errors (1000s)
+    CONNECTION_FAILED = 1000
+    CONNECTION_REFUSED = 1001
+    AUTH_FAILED = 1002
+
+    # Request errors (2000s)
+    REQUEST_FAILED = 2000
+    RESOURCE_NOT_FOUND = 2001
+
+    # Validation errors (3000s)
+    VALIDATION_FAILED = 3000
+    INVALID_PARAMETER = 3001
+    MISSING_PARAMETER = 3002
+    VALUE_OUT_OF_RANGE = 3003
+
+
+class OBSMCPError(Exception):
+    def __init__(self, code: ErrorCode, message: str):
+        self.code = code
+        self.message = message
+        super().__init__(f"[{code.name} ({code.value})] {message}")

obs_mcp/main.py

@@ -0,0 +1,43 @@
+"""OBS-MCP server entry point."""
+
+import logging
+import sys
+
+from mcp.server.fastmcp import FastMCP
+
+from obs_mcp.obs_client import OBSClient
+from obs_mcp.tool_registry import register_all_tools
+
+logging.basicConfig(level=logging.INFO, stream=sys.stderr)
+logger = logging.getLogger(__name__)
+
+# obsws-python logs the OBS password in plaintext ("Connecting with
+# parameters: ... password='...'") at INFO on every connect. Raise it above
+# our own INFO level so that line never reaches stderr (and whatever log
+# file the MCP client persists stderr to).
+logging.getLogger("obsws_python").setLevel(logging.WARNING)
+
+client = OBSClient()
+
+mcp = FastMCP(
+    "obs-mcp",
+    instructions=(
+        "Control OBS Studio via obs-websocket v5. Requires OBS Studio running "
+        "with Tools > WebSocket Server Settings enabled. Connection defaults "
+        "to localhost:4455 with no password — override with OBS_HOST/OBS_PORT/"
+        "OBS_PASSWORD environment variables if yours differs.\n\n"
+        "Scene and source names are case-sensitive and must match exactly "
+        "what's shown in OBS. Use get_scene_list / get_input_list to see "
+        "exact names before acting on them."
+    ),
+)
+
+register_all_tools(mcp)
+
+
+def main():
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

obs_mcp/obs_client.py

@@ -0,0 +1,91 @@
+"""Async wrapper around obsws-python's synchronous ReqClient.
+
+obsws-python's ReqClient blocks on the underlying WebSocket call; every
+request here runs in a thread-pool executor so FastMCP's async tool
+functions never block the event loop on OBS round-trips.
+"""
+
+import asyncio
+import logging
+import os
+
+import obsws_python as obsws
+from obsws_python.error import OBSSDKRequestError
+
+from obs_mcp.error_codes import ErrorCode, OBSMCPError
+
+logger = logging.getLogger(__name__)
+
+
+class OBSClient:
+    def __init__(self):
+        self._client: obsws.ReqClient | None = None
+        self._lock = asyncio.Lock()
+
+    def _connect_sync(self) -> obsws.ReqClient:
+        host = os.environ.get("OBS_HOST", "localhost")
+        port = int(os.environ.get("OBS_PORT", "4455"))
+        password = os.environ.get("OBS_PASSWORD", "")
+        try:
+            return obsws.ReqClient(host=host, port=port, password=password, timeout=5)
+        except Exception as e:
+            raise OBSMCPError(
+                ErrorCode.CONNECTION_FAILED,
+                f"Could not connect to OBS at {host}:{port} — {e}. "
+                f"Make sure OBS Studio is running with the WebSocket server "
+                f"enabled (Tools > WebSocket Server Settings) and that "
+                f"OBS_HOST/OBS_PORT/OBS_PASSWORD match its settings.",
+            )
+
+    async def _ensure_connected_locked(self) -> obsws.ReqClient:
+        """Must be called with self._lock already held."""
+        if self._client is None:
+            loop = asyncio.get_running_loop()
+            self._client = await loop.run_in_executor(None, self._connect_sync)
+        return self._client
+
+    async def execute(self, request_type: str, **data) -> dict:
+        """Call any obs-websocket v5 request by name. Returns response fields as a dict.
+
+        obsws-python's req() does a bare send() then recv() with no request-ID
+        matching, so it isn't safe to call from two threads at once — a second
+        concurrent request can steal the first request's response off the
+        socket. Serialize every call (connect included) through one lock so
+        concurrent tool calls queue instead of racing.
+        """
+        loop = asyncio.get_running_loop()
+        async with self._lock:
+            client = await self._ensure_connected_locked()
+            try:
+                result = await loop.run_in_executor(
+                    None, lambda: client.send(request_type, data if data else None, raw=True)
+                )
+            except OBSSDKRequestError as e:
+                # OBS replied — the request was just invalid (bad scene name,
+                # out-of-range value, etc). The socket is still healthy, so
+                # don't force a reconnect for something that isn't a
+                # connection problem; the AI will hit this routinely while
+                # exploring scene/source names.
+                raise OBSMCPError(
+                    ErrorCode.REQUEST_FAILED,
+                    f"OBS request '{request_type}' failed: {e}",
+                )
+            except Exception as e:
+                # No reply came back at all — the connection itself is dead.
+                # Reset so the next call reconnects instead of failing forever.
+                self._client = None
+                raise OBSMCPError(
+                    ErrorCode.REQUEST_FAILED,
+                    f"OBS request '{request_type}' failed: {e}",
+                )
+        if result is None:
+            return {}
+        return result if isinstance(result, dict) else result.__dict__
+
+    async def close(self):
+        if self._client is not None:
+            try:
+                self._client.disconnect()
+            except Exception:
+                pass
+            self._client = None

obs_mcp/tool_registry.py

@@ -0,0 +1,61 @@
+import importlib
+import logging
+import pkgutil
+import sys
+
+from mcp.server.fastmcp import FastMCP
+
+import obs_mcp.tools as tools_package
+
+logger = logging.getLogger(__name__)
+
+# Every module that should exist on disk in a healthy checkout — update this
+# when adding a new obs_mcp/tools/*.py module. Lets startup fail loud if a
+# module goes missing instead of silently shipping fewer tools than intended.
+_EXPECTED_MODULES = frozenset({
+    "general_tools", "config_tools", "source_tools", "scene_tools",
+    "input_tools", "transition_tools", "filter_tools", "scene_item_tools",
+    "output_tools", "stream_record_tools", "media_tools", "ui_tools",
+    "pipeline_tools",
+})
+
+
+def register_all_tools(mcp: FastMCP):
+    """Discover and register every tool module in obs_mcp/tools/."""
+    failures: list[tuple[str, Exception]] = []
+    registered: list[str] = []
+
+    for _finder, name, _ispkg in pkgutil.iter_modules(tools_package.__path__):
+        try:
+            module = importlib.import_module(f"obs_mcp.tools.{name}")
+        except Exception as e:
+            logger.error("IMPORT FAILED for tool module %s: %s", name, e, exc_info=True)
+            sys.stderr.write(f"\n[obs-mcp] ERROR: Failed to import tool module '{name}': {e}\n")
+            failures.append((name, e))
+            continue
+
+        if not hasattr(module, "register"):
+            continue
+
+        try:
+            module.register(mcp)
+            registered.append(name)
+        except Exception as e:
+            logger.error("REGISTER FAILED for %s: %s", name, e, exc_info=True)
+            sys.stderr.write(f"\n[obs-mcp] ERROR: Tool registration failed for '{name}': {e}\n")
+            failures.append((name, e))
+
+    sys.stderr.write(f"[obs-mcp] Registered {len(registered)} tool module(s)\n")
+
+    missing = _EXPECTED_MODULES - set(registered) - {n for n, _ in failures}
+    if missing:
+        sys.stderr.write(
+            f"[obs-mcp] WARNING: expected module(s) not found on disk: {sorted(missing)}. "
+            f"This install is incomplete.\n"
+        )
+
+    if failures:
+        sys.stderr.write(
+            f"[obs-mcp] WARNING: {len(failures)} tool module(s) failed to load: "
+            f"{', '.join(n for n, _ in failures)}\n"
+        )

obs_mcp/tools/config_tools.py

@@ -0,0 +1,136 @@
+"""Config tools — scene collections, profiles, video settings, stream service, record directory."""
+
+from mcp.server.fastmcp import FastMCP
+
+from obs_mcp.error_codes import ErrorCode, OBSMCPError
+
+
+def register(mcp: FastMCP):
+    from obs_mcp.main import client
+
+    # ── Scene collections ──────────────────────────────────────
+    @mcp.tool()
+    async def get_scene_collection_list() -> dict:
+        """List all scene collections and the currently active one."""
+        return await client.execute("GetSceneCollectionList")
+
+    @mcp.tool()
+    async def set_current_scene_collection(name: str) -> dict:
+        """Switch to a scene collection by name. Blocks until the switch completes."""
+        return await client.execute("SetCurrentSceneCollection", sceneCollectionName=name)
+
+    @mcp.tool()
+    async def create_scene_collection(name: str) -> dict:
+        """Create a new scene collection and switch to it."""
+        return await client.execute("CreateSceneCollection", sceneCollectionName=name)
+
+    # ── Profiles ──────────────────────────────────────
+    @mcp.tool()
+    async def get_profile_list() -> dict:
+        """List all profiles and the currently active one."""
+        return await client.execute("GetProfileList")
+
+    @mcp.tool()
+    async def set_current_profile(name: str) -> dict:
+        """Switch to a profile by name."""
+        return await client.execute("SetCurrentProfile", profileName=name)
+
+    @mcp.tool()
+    async def create_profile(name: str) -> dict:
+        """Create a new profile and switch to it."""
+        return await client.execute("CreateProfile", profileName=name)
+
+    @mcp.tool()
+    async def remove_profile(name: str) -> dict:
+        """Remove a profile. If it's the active one, OBS switches away first."""
+        return await client.execute("RemoveProfile", profileName=name)
+
+    @mcp.tool()
+    async def get_profile_parameter(category: str, name: str) -> dict:
+        """Read a raw parameter from the current profile's .ini configuration.
+
+        Args:
+            category: Config category, e.g. "Output".
+            name: Parameter name within that category.
+        """
+        return await client.execute("GetProfileParameter", parameterCategory=category, parameterName=name)
+
+    @mcp.tool()
+    async def set_profile_parameter(category: str, name: str, value: str | None) -> dict:
+        """Write a raw parameter into the current profile's .ini configuration.
+        Advanced/low-level — prefer a dedicated request when one exists.
+
+        Args:
+            category: Config category, e.g. "Output".
+            name: Parameter name within that category.
+            value: New value, or None to delete the parameter.
+        """
+        return await client.execute("SetProfileParameter", parameterCategory=category, parameterName=name, parameterValue=value)
+
+    # ── Video settings ──────────────────────────────────────
+    @mcp.tool()
+    async def get_video_settings() -> dict:
+        """Current canvas/output resolution and FPS (as a fraction — divide
+        fpsNumerator by fpsDenominator for the true FPS)."""
+        return await client.execute("GetVideoSettings")
+
+    @mcp.tool()
+    async def set_video_settings(
+        fps_numerator: int | None = None, fps_denominator: int | None = None,
+        base_width: int | None = None, base_height: int | None = None,
+        output_width: int | None = None, output_height: int | None = None,
+    ) -> dict:
+        """Change canvas/output resolution and/or FPS. Width/height fields must
+        be set in pairs (can't change baseWidth without baseHeight, etc).
+        Range 1-4096 for all resolution fields.
+        """
+        params = {}
+        if fps_numerator is not None:
+            params["fpsNumerator"] = fps_numerator
+        if fps_denominator is not None:
+            params["fpsDenominator"] = fps_denominator
+        if base_width is not None:
+            params["baseWidth"] = base_width
+        if base_height is not None:
+            params["baseHeight"] = base_height
+        if output_width is not None:
+            params["outputWidth"] = output_width
+        if output_height is not None:
+            params["outputHeight"] = output_height
+        return await client.execute("SetVideoSettings", **params)
+
+    # ── Stream service settings ──────────────────────────────────────
+    @mcp.tool()
+    async def get_stream_service_settings() -> dict:
+        """Current stream destination service type and settings (server/key etc)."""
+        return await client.execute("GetStreamServiceSettings")
+
+    @mcp.tool()
+    async def set_stream_service_settings(service_type: str, settings: dict) -> dict:
+        """Set the stream destination. For a plain custom RTMP target, use
+        service_type="rtmp_custom" and settings={"server": "...", "key": "..."}.
+
+        Args:
+            service_type: e.g. "rtmp_custom" or "rtmp_common".
+            settings: Service-specific settings object.
+        """
+        return await client.execute(
+            "SetStreamServiceSettings", streamServiceType=service_type, streamServiceSettings=settings,
+        )
+
+    # ── Record directory ──────────────────────────────────────
+    @mcp.tool()
+    async def get_record_directory() -> dict:
+        """Current output directory for recordings."""
+        return await client.execute("GetRecordDirectory")
+
+    @mcp.tool()
+    async def set_record_directory(path: str) -> dict:
+        """Set the output directory recordings are written to.
+
+        Args:
+            path: Absolute directory path.
+        """
+        if not path:
+            raise OBSMCPError(ErrorCode.MISSING_PARAMETER, "path is required")
+        return await client.execute("SetRecordDirectory", recordDirectory=path)

obs_mcp/tools/filter_tools.py

@@ -0,0 +1,106 @@
+"""Filter tools — raw CRUD on source filters (audio/video effects chains).
+For a one-call noise-free mic setup, see pipeline_tools.clean_audio_input instead
+of hand-assembling a filter chain with these."""
+
+from mcp.server.fastmcp import FastMCP
+
+from obs_mcp.error_codes import ErrorCode, OBSMCPError
+
+
+def register(mcp: FastMCP):
+    from obs_mcp.main import client
+
+    @mcp.tool()
+    async def get_source_filter_kind_list() -> dict:
+        """List every filter kind this OBS install supports (noise_suppress_filter,
+        noise_gate_filter, compressor_filter, color_filter, chroma_key_filter, etc)."""
+        return await client.execute("GetSourceFilterKindList")
+
+    @mcp.tool()
+    async def get_source_filter_list(source_name: str) -> dict:
+        """List all filters on a source (input or scene), in chain order.
+
+        Args:
+            source_name: Name of the source.
+        """
+        return await client.execute("GetSourceFilterList", sourceName=source_name)
+
+    @mcp.tool()
+    async def get_source_filter_default_settings(filter_kind: str) -> dict:
+        """Default settings object for a filter kind."""
+        return await client.execute("GetSourceFilterDefaultSettings", filterKind=filter_kind)
+
+    @mcp.tool()
+    async def create_source_filter(
+        source_name: str, filter_name: str, filter_kind: str, filter_settings: dict | None = None,
+    ) -> dict:
+        """Add a new filter to a source.
+
+        Args:
+            source_name: Name of the source to add the filter to.
+            filter_name: Name for the new filter.
+            filter_kind: Filter kind (see get_source_filter_kind_list).
+            filter_settings: Optional initial settings.
+        """
+        if not source_name or not filter_name or not filter_kind:
+            raise OBSMCPError(ErrorCode.MISSING_PARAMETER, "source_name, filter_name, and filter_kind are required")
+        return await client.execute(
+            "CreateSourceFilter", sourceName=source_name, filterName=filter_name,
+            filterKind=filter_kind, filterSettings=filter_settings or {},
+        )
+
+    @mcp.tool()
+    async def remove_source_filter(source_name: str, filter_name: str) -> dict:
+        """Remove a filter from a source."""
+        if not source_name or not filter_name:
+            raise OBSMCPError(ErrorCode.MISSING_PARAMETER, "source_name and filter_name are required")
+        return await client.execute("RemoveSourceFilter", sourceName=source_name, filterName=filter_name)
+
+    @mcp.tool()
+    async def set_source_filter_name(source_name: str, filter_name: str, new_filter_name: str) -> dict:
+        """Rename a filter."""
+        return await client.execute(
+            "SetSourceFilterName", sourceName=source_name, filterName=filter_name, newFilterName=new_filter_name,
+        )
+
+    @mcp.tool()
+    async def get_source_filter(source_name: str, filter_name: str) -> dict:
+        """Get a filter's enabled state, chain index, kind, and settings."""
+        return await client.execute("GetSourceFilter", sourceName=source_name, filterName=filter_name)
+
+    @mcp.tool()
+    async def set_source_filter_index(source_name: str, filter_name: str, filter_index: int) -> dict:
+        """Reorder a filter within a source's filter chain.
+
+        Args:
+            source_name: Name of the source.
+            filter_name: Name of the filter to move.
+            filter_index: New position, >= 0 (0 = first in chain).
+        """
+        if filter_index < 0:
+            raise OBSMCPError(ErrorCode.VALUE_OUT_OF_RANGE, "filter_index must be >= 0")
+        return await client.execute(
+            "SetSourceFilterIndex", sourceName=source_name, filterName=filter_name, filterIndex=filter_index,
+        )
+
+    @mcp.tool()
+    async def set_source_filter_settings(source_name: str, filter_name: str, filter_settings: dict, overlay: bool = True) -> dict:
+        """Configure a filter's parameters.
+
+        Args:
+            source_name: Name of the source.
+            filter_name: Name of the filter.
+            filter_settings: Settings object.
+            overlay: True = merge on top of current settings, False = reset to defaults first.
+        """
+        return await client.execute(
+            "SetSourceFilterSettings", sourceName=source_name, filterName=filter_name,
+            filterSettings=filter_settings, overlay=overlay,
+        )
+
+    @mcp.tool()
+    async def set_source_filter_enabled(source_name: str, filter_name: str, filter_enabled: bool) -> dict:
+        """Enable or disable a filter without removing it."""
+        return await client.execute(
+            "SetSourceFilterEnabled", sourceName=source_name, filterName=filter_name, filterEnabled=filter_enabled,
+        )

obs_mcp/tools/general_tools.py

@@ -0,0 +1,105 @@
+"""General OBS tools — version/stats, hotkeys, custom events, vendor requests."""
+
+from mcp.server.fastmcp import FastMCP
+
+
+def register(mcp: FastMCP):
+    from obs_mcp.main import client
+
+    @mcp.tool()
+    async def get_version() -> dict:
+        """OBS/obs-websocket version info, platform, and the full list of requests
+        available on this connection (availableRequests)."""
+        return await client.execute("GetVersion")
+
+    @mcp.tool()
+    async def get_stats() -> dict:
+        """Live perf stats: CPU/memory usage, active FPS, render/output skipped
+        frames, disk space. Use to check for dropped-frame problems mid-stream."""
+        return await client.execute("GetStats")
+
+    @mcp.tool()
+    async def broadcast_custom_event(event_data: dict) -> dict:
+        """Broadcast a CustomEvent to all subscribed obs-websocket clients.
+
+        Args:
+            event_data: Arbitrary JSON payload delivered to receivers.
+        """
+        return await client.execute("BroadcastCustomEvent", eventData=event_data)
+
+    @mcp.tool()
+    async def call_vendor_request(vendor_name: str, request_type: str, request_data: dict | None = None) -> dict:
+        """Call a request registered by a third-party OBS plugin/script vendor.
+
+        Args:
+            vendor_name: Unique vendor name registered by the plugin.
+            request_type: The vendor's request type to call.
+            request_data: Optional payload for the vendor request.
+        """
+        return await client.execute(
+            "CallVendorRequest",
+            vendorName=vendor_name, requestType=request_type,
+            requestData=request_data or {},
+        )
+
+    @mcp.tool()
+    async def get_hotkey_list() -> dict:
+        """List all hotkey names in OBS. Best-effort — hotkey requests are less
+        reliable than dedicated requests when one exists for the same action."""
+        return await client.execute("GetHotkeyList")
+
+    @mcp.tool()
+    async def trigger_hotkey_by_name(hotkey_name: str, context_name: str = "") -> dict:
+        """Trigger a hotkey by its name (see get_hotkey_list).
+
+        Args:
+            hotkey_name: Name of the hotkey to trigger.
+            context_name: Optional hotkey context name.
+        """
+        params = {"hotkeyName": hotkey_name}
+        if context_name:
+            params["contextName"] = context_name
+        return await client.execute("TriggerHotkeyByName", **params)
+
+    @mcp.tool()
+    async def trigger_hotkey_by_key_sequence(
+        key_id: str = "", shift: bool = False, control: bool = False,
+        alt: bool = False, command: bool = False,
+    ) -> dict:
+        """Trigger a hotkey by simulating a key press + modifiers.
+
+        Args:
+            key_id: OBS key ID (see obs-studio's obs-hotkeys.h for the list).
+            shift/control/alt/command: Modifier keys to hold.
+        """
+        params = {}
+        if key_id:
+            params["keyId"] = key_id
+        params["keyModifiers"] = {
+            "shift": shift, "control": control, "alt": alt, "command": command,
+        }
+        return await client.execute("TriggerHotkeyByKeySequence", **params)
+
+    @mcp.tool()
+    async def get_persistent_data(realm: str, slot_name: str) -> dict:
+        """Get a value from an OBS persistent-data "slot".
+
+        Args:
+            realm: "OBS_WEBSOCKET_DATA_REALM_GLOBAL" or "OBS_WEBSOCKET_DATA_REALM_PROFILE".
+            slot_name: Name of the slot to read.
+        """
+        return await client.execute("GetPersistentData", realm=realm, slotName=slot_name)
+
+    @mcp.tool()
+    async def set_persistent_data(realm: str, slot_name: str, slot_value) -> dict:
+        """Set a value in an OBS persistent-data "slot" — useful for storing state
+        the AI needs to remember across tool calls (e.g. giveaway winners).
+
+        Args:
+            realm: "OBS_WEBSOCKET_DATA_REALM_GLOBAL" or "OBS_WEBSOCKET_DATA_REALM_PROFILE".
+            slot_name: Name of the slot to write.
+            slot_value: Any JSON-serializable value.
+        """
+        return await client.execute(
+            "SetPersistentData", realm=realm, slotName=slot_name, slotValue=slot_value,
+        )