Roblox Studio MCP to Notion Bridge

This project solves the architectural incompatibility between the official Roblox Studio MCP (Model Context Protocol) and stateless cloud agents (like Notion AI).

⚠️ The Problem

The official Roblox Studio MCP runs locally as a stdio executable (StudioMCP.exe). Tools like Cursor or local Claude apps connect to it directly via child processes. They keep the connection open forever, which maintains the "Active Studio" state.

However, cloud-based agents like Notion communicate over HTTP/SSE. Notion connects, executes a tool, and drops the connection. When it reconnects, it spins up a new local MCP process that has forgotten which Studio instance is active. Because of this, trying to use supergateway out-of-the-box results in crashes, lost state, and the inability to execute complex tasks like getting the DataModel tree.

🛠️ The Solution

This bridge creates a Persistent Multiplexer.

1. mcp-server.js launches a single, global instance of StudioMCP.exe in the background and keeps it alive forever.
2. It listens for incoming transient SSE connections from the cloud (Notion).
3. It intercepts and filters out unsolicited notifications/tools/list_changed events that otherwise cause Notion's MCP client to crash.
4. proxy.js adds a layer of Bearer Token authentication so you can safely expose the bridge to the public internet via a tunnel.

🚀 Setup Instructions

1. Installation

Clone this repository and install the dependencies:

npm install

2. Configuration

Copy the .env.example file to .env:

cp .env.example .env

Open .env and fill in your details:

• PUBLIC_URL: The public HTTPS URL where your tunnel is hosted (e.g. https://roblox.your-domain.com). This is required so the SSE endpoint can tell Notion where to send POST messages.
• AUTH_TOKEN: Create a secure, random string (e.g. my-super-secret-token-123).

3. Start the Bridge

Run the launcher script:

start-bridge.bat

This will open two terminal windows: one for the MCP Server (Port 8000) and one for the Auth Proxy (Port 8001).

4. Create a Tunnel

You must expose Port 8001 to the internet. You can use Cloudflare Tunnels, ngrok, or a reverse SSH tunnel. Example using Cloudflare:

cloudflared tunnel --url http://localhost:8001

5. Connect Notion (Standard Chat Workflow)

You do NOT need to use "Custom Agents" (which consume expensive credits). You can connect this MCP server directly to a standard Notion AI chat!

Simply open a new standard chat in Notion and paste the following text:

Connect to my Roblox Studio MCP tunnel using this data:
MCP URL: https://<YOUR_TUNNEL_URL>/sse
Auth method: Bearer Token
Token: <YOUR_AUTH_TOKEN>
Transport: SSE

Notion will automatically display a connection window. Confirm the details, and the standard Notion AI will instantly connect to your local Roblox Studio and gain access to the full suite of tools (reading/writing scripts, exploring the DataModel, etc.)!

6. Agent Instructions Prompt

To ensure the AI knows how to work with your Studio, send it this prompt after connecting:

You are an expert Roblox Studio assistant. You are connected to my local Roblox Studio via an MCP SSE Bridge.

**Initialization Check:**
If you do not see advanced tools like `get_tree` or `execute_script`, it means the server needs to be initialized. In that case:
1. Call `list_roblox_studios` to find the active studio ID.
2. Call `set_active_studio` with that ID.
3. Stop and ask me to reply "continue" so your tools refresh.

**Workflow:**
- Always inspect the DataModel (`get_tree`) and read scripts before proposing changes.
- Prefer small, targeted code edits. Preserve existing architecture and naming conventions.
- Never make destructive changes without asking first.
- If a test cannot be executed via MCP, suggest specific Studio play-test steps.

Enjoy seamless, cloud-based Roblox game development directly in Notion!