Control Social Stream Ninja with AI

Let an AI tool on the same computer manage sources and supported settings through an opt-in localhost API.

1. Download the normal desktop app

Install Social Stream Ninja from the Windows, macOS, or Linux downloads. Downloaded-app MCP support is included in SSApp 0.4.7 and newer. You do not need the source repository, Node, Python, or a separate MCP package.

2. Enable local AI control

  1. Open File > Local AI / Automation.
  2. Enable Local Control API and let the app restart.
  3. Return to the same menu and choose Copy MCP Setup.
  4. Paste the copied JSON into the MCP settings used by the AI tool, then restart that tool.

The copied setup contains the exact installed executable path, port, and platform-specific arguments. The downloaded Social Stream Ninja executable starts its own lightweight MCP adapter when the AI client launches it with --ssapp-mcp.

3. Let MCP perform discovery

Once connected, the MCP client automatically asks Social Stream Ninja for its tools. The adapter reads the running app's live capabilities and gives the LLM the supported tool schemas, app/API versions, and operating instructions. The agent should call capabilities first, then status, and use the stable source IDs returned by the app.

No website scraping or skill installation is required for normal MCP use. A user can simply ask the connected agent to inspect or control Social Stream Ninja.

Available local controls

  • List, inspect, add, update, and remove sources.
  • Start, stop, or reload one source or a filtered set.
  • Change source visibility, mute state, and connection mode.
  • Read and update the supported global settings returned by capability discovery.
  • Read app, session, source, and local-media server status.
  • Follow resumable status and operation events for long-running automation.
  • Reload or gracefully shut down the app with explicit confirmation.

Direct HTTP access for local scripts

Scripts on the same computer can use the loopback API without MCP. It listens only on 127.0.0.1 and does not require a token.

GET http://127.0.0.1:17777/api/v1/capabilities
GET http://127.0.0.1:17777/api/v1/status
GET http://127.0.0.1:17777/api/v1/events
POST http://127.0.0.1:17777/api/v1/command

Use the advertised capabilities instead of assuming every app version has the same controls.

Downloaded AppImage on an Ubuntu VPS

The main application still needs Xvfb because source capture uses real Electron windows. The MCP adapter itself can use Electron's headless platform. Replace the example filename with the AppImage you downloaded.

sudo apt-get install -y xvfb
chmod +x /opt/socialstream/socialstreamninja.AppImage
export SSAPP_USER_DATA_DIR=/var/lib/ssapp
xvfb-run -a -s "-screen 0 1920x1080x24 -nolisten tcp -extension GLX" \
  /opt/socialstream/socialstreamninja.AppImage \
  --ssapp-headless-control --ssapp-control-api --no-hwa

Register the same downloaded file as the MCP command:

{
  "mcpServers": {
    "social-stream": {
      "command": "/opt/socialstream/socialstreamninja.AppImage",
      "args": ["--ssapp-mcp", "--ozone-platform=headless"],
      "env": {"SSAPP_CONTROL_URL": "http://127.0.0.1:17777"}
    }
  }
}

Optional agent skill

Agents that support installable skills can download the complete Control Social Stream skill. You can also read its instructions online, with the API reference and version log. The skill adds workflow guidance but is not needed for MCP connectivity.

Machine-readable discovery links are also listed in llms.txt.

Local only

This interface is for AI and automation running on the same computer as SSApp. Do not expose or tunnel it as a cloud remote-control API. Remote users and Stream Deck should use Social Stream's existing WebRTC or WebSocket connection. The local API does not provide arbitrary JavaScript execution, cookies, sign-in secrets, unrestricted settings, or raw filesystem access.