ultra/mcp-ss is a FastAPI-based MCP server that integrates with smartscreen.tv, a web display service, allowing you to programmatically manipulate the screen (e.g., display media, send notifications, control playback) via simple HTTP/MCP commands.

Table of Contents

• What is SmartScreen?

• Prerequisites

• Configuration

• Running Locally

• Docker

• API Endpoints

  • Health & Search
  • SmartScreen Commands (HTTP)

• MCP Tool Integration

• Using MCP Proxy for Clients Without SSE Support

• Setting up MCP-SS in Langflow

• Contributing

What is SmartScreen?

SmartScreen is a web-based screening service.
Content across multiple displays and locations can be controlled remotely. Simply add the MCP tool to your AI app.

SmartScreen setup:

1. Access SmartScreen through URL: smartscreen.tv
   
   • On Linux, SmartScreen can be installed via snapcraft.
2. Click the menu button on the top-left corner to reach Settings. Here you can name your device, add tags, and set up OnStart and other scheduled events.
   
   • Don’t forget to click “Save” after making any changes.
3. Click SmartScreen to return to the Home Page.

ultra/mcp-ss

Prerequisites

• Python 3.12+
• Docker (optional, for containerized deployment)
• YOUTUBE_API_KEY set up from Google Console for "YouTube Data API v3"
• SS_SERVICE_TOKEN environment variable

Configuration

Create a .env file or export environment variables:

• YOUTUBE_API_KEY – your Google YouTube Data API v3 key
• SS_SERVICE_TOKEN – SmartScreen service token

Example .env:

YOUTUBE_API_KEY=AIzaSy...
SS_SERVICE_TOKEN=xxxxx

or export them:

export YOUTUBE_API_KEY=AIzaSy...
export SS_SERVICE_TOKEN=xxxxx

Running Locally

uvicorn main:app --reload --host 0.0.0.0 --port 8000

Docker

docker build -t ultra-mcp-ss .
docker run -d --name ultra-mcp-ss -p 127.0.0.1:8000:8000 ultra-mcp-ss

API Endpoints

Base URL: http://127.0.0.1:8000

Health & Search

• HEAD /mcp – health check for MCP
• GET /search-youtube?query=... – returns the most relevant YouTube video URL

SmartScreen Commands (HTTP)

Endpoint	Description
POST /drop	Drop media URL onto a screen frame
POST /notify	Send a notification banner
POST /toast	Show a toast popup message
POST /marquee	Display scrolling marquee text
POST /text	Render static text overlay
POST /app	Launch a web app in a frame
POST /touch	Send playback/control commands
POST /status	Query or set system status
POST /dj	Execute DJ tasks: scheduling, kiosk, restart, logo

Refer to OpenAPI docs at http://<host>:8000/docs for request/response schemas.

MCP Tool Integration

FastApiMCP automatically mounts all endpoints as MCP tools under /mcp.
Use your MCP client to invoke tools by name (e.g., drop, notify, toast, etc.).

Using MCP Proxy for Clients Without SSE Support (Claude Desktop)

1. Install mcp-proxy:

   uv pip install --user mcp-proxy #for Python
   npm install -g mcp-proxy #for Node.js
   pnpm add -g mcp-proxy #for Node.js
    
   

2. On Windows:
   Edit claude_desktop_config.json:

   {
     "mcpServers": {
       "ultra-mcp-ss": {
         "command": "mcp-proxy",
         "args": ["http://0.0.0.0:8000/mcp"]
       }
     }
   }
   

3. On MacOS:
   Get the path to mcp-proxy:

   which mcp-proxy
   

   Edit claude_desktop_config.json:

   {
     "mcpServers": {
       "ultra-mcp-ss": {
         "command": "/YOUR/PATH/TO/mcp-proxy",
         "args": ["http://0.0.0.0:8000/mcp"]
       }
     }
   }
   

Setting up MCP-SS in Langflow

To integrate ultra-mcp-ss with Langflow:

1. Add MCP Server component from the Tool section in Langflow
2. Enable Tool Mode in the component settings
3. Select SSE Mode for real-time communication
4. Enter the MCP SSE URL: http://0.0.0.0:8000/mcp
5. Use http://127.0.0.1:8000 if running using Docker.
6. Run the component to establish connection

Once connected, you can use all SmartScreen commands within your Langflow workflows.

Contributing

1. Fork the repo
2. Create a feature branch
3. Submit a pull request

---

Made with FastAPI & FastApiMCP