Notion MCP Workspace (remake)

Two MCP servers for coding from Notion on this Windows machine, with token auth, live project switching and a Cloudflare Tunnel. Pure Python.

See ARCHITECTURE.md for the design and the reasoning behind it.

Setup on a New Machine (Quickstart for Teammates)

1. Prerequisites (Windows)

1. Python 3.10+: Download from python.org (make sure to check "Add python.exe to PATH").

2. Cloudflare Tunnel CLI (cloudflared): Open PowerShell and install via winget:

   winget install Cloudflare.cloudflared

   (Or download cloudflared-windows-amd64.exe from Cloudflare GitHub releases, rename to cloudflared.exe, and add to PATH).

2. Install Project Dependencies

Open a terminal in the project folder:

pip install -r requirements.txt

(Optionally use a virtualenv: python -m venv .venv && .venv\Scripts\activate && pip install -r requirements.txt)

3. Sharing Project with Others (Clean Zip / Clone)

If sharing as a .zip archive, exclude these machine-specific files:

• config/settings.json (created automatically on first launch with clean defaults)

• __pycache__/

• .mcp-runs/ and .mcp-backups/

4. Run the Control Panel

Double click start_gui.bat or run:

python -m gui.app

On first start:

1. In the Cloudflare tunnel card, set your Base domain (e.g. wolroom.store) and your unique User prefix (e.g. alex).

2. Point cloudflared config to your tunnel credentials (~/.cloudflared/config.yml).

3. Click Start everything in the top bar.

4. Click Notion setup guide to copy endpoints and add skills directly into Notion.

Headless:

python run_core.py                # servers + tunnel
python run_core.py --no-tunnel    # local only
python run_core.py --print-config # token, ports, projects, endpoints

Settings-only commands (safer than editing the JSON by hand):

python run_core.py --set-tunnel-config "C:\Users\Dima\.cloudflared\config.yml"
python run_core.py --files-hostname mcp-files.wolroom.store
python run_core.py --terminal-hostname mcp-term.wolroom.store
python run_core.py --enable-tunnel
python run_core.py --disable-tunnel
python run_core.py --regenerate-token

Settings live in config\settings.json, created on first run from the defaults. It holds the auth token, ports, tunnel setup, limits and the project registry. If the file ever becomes invalid JSON, it is moved aside as settings.broken.json and recreated from defaults - which is why hand editing is discouraged.

Only one instance can hold the ports at a time: do not run run_core.py and the control panel simultaneously.

Related MCP server: win-cli-mcp-tmyy

Control panel

gui/ is a PySide6 app styled after shadcn/ui (zinc palette, flat cards, subtle borders). It imports the same ServerSupervisor the CLI uses, so both entry points behave identically.

• Servers card: status badge, start / stop / restart, local URLs with copy

• Tunnel card: status badge, start / stop, public URLs, config file picker

• Projects card: list, add folder, remove, set active

• Authentication card: reveal / copy / regenerate the token

• Activity card: live log from the servers and cloudflared

• "Notion setup guide" button: a separate modal with the whole onboarding - endpoint URLs, token, a ready-made "connect an MCP server" request, the full skill text with a copy button, daily-use habits and troubleshooting

Test

python tests\smoke_test.py

Starts both servers on ports 9400 / 9401 with a throwaway settings file and checks auth and the tool lists. Safe to run while anything else is live.

Tools

Files System - list_directory, read_file, read_multiple_files, write_file, edit_file, create_directory, move_file, delete_file, search_files, grep, get_file_info

Terminal - run_command, get_active_project, list_skills, get_skill

Paths may be absolute or relative to the active project. Relative is preferred: it keeps working after the user switches projects.

Projects

The active project decides where relative paths resolve and where commands run. It is read on every tool call, so switching takes effect immediately with no restart.

By default, paths outside the active project root are refused. Set security.allow_outside_project to true to lift that.

Auth

Every request needs the token from config\settings.json:

Authorization: Bearer <token>

X-API-Key and X-Auth-Token are accepted too, for clients that cannot send an Authorization header. Requests without a valid token get 401 before reaching any tool. Use header-based auth when adding the connection in Notion.

The token is generated once and reused across restarts. It only changes if you regenerate it, which invalidates the connections already added in Notion.

Ports

Defaults are 9500 (Files System) and 9501 (Terminal). The old gateway still owns 9300 / 9301, so both stacks can run side by side; the cloudflared ingress must point at whichever ports are configured here.

Cloudflare Tunnel

One-time setup:

cloudflared tunnel login
cloudflared tunnel create notion-sync
cloudflared tunnel route dns notion-sync mcp-files.wolroom.store
cloudflared tunnel route dns notion-sync mcp-term.wolroom.store

Ingress in the cloudflared config, keeping http_status:404 last:

tunnel: notion-sync
credentials-file: C:\Users\Dima\.cloudflared\<tunnel-id>.json
ingress:
  - hostname: cmd.wolroom.store
    service: http://localhost:8734
  - hostname: mcp-files.wolroom.store
    service: http://localhost:9500
  - hostname: mcp-term.wolroom.store
    service: http://localhost:9501
  - service: http_status:404

cmd.wolroom.store stays as a fallback to the legacy command server.

cloudflared runs as a child process: it starts with the app and is terminated when the app exits.

Notion endpoints:

• Files System: https://mcp-files.wolroom.store/mcp

• Terminal: https://mcp-term.wolroom.store/mcp

Status

Done: settings store, project registry, path sandbox, logging, process supervisor, both MCP servers, bearer auth, tunnel wiring, smoke test, control panel with the Notion setup guide.

Next: session identification experiments, then agent memory across chats.