random-mcp

Ein eigener MCP-Server, der Claude echte Zufallszahlen liefert, statt dass Claude sich selbst Zahlen ausdenkt. Läuft als Cloudflare Worker im kostenlosen Tarif, ohne eigenen Rechner.

Werkzeuge

Alle Werkzeuge gibt es auf zwei Wegen:

• MCP für LLMs wie Claude: https://random-mcp.<konto>.workers.dev/mcp

• REST für Browser, Skripte, Apps: GET https://random-mcp.<konto>.workers.dev/api/<werkzeug>?...

• Demo-Seite mit Knöpfen zum Ausprobieren: https://random-mcp.<konto>.workers.dev/

Jede Antwort enthält das Feld quelle, damit Claude sagen kann, woher die Zahlen kommen.

Zufallsquelle (Stufe 1): crypto.getRandomValues() von Cloudflare Workers, ein kryptografisch sicherer Generator, gespeist aus Hardware-Entropie. Zahlen in einem Bereich werden per Rejection Sampling gezogen (keine Verzerrung), Listen per Fisher-Yates gemischt.

Related MCP server: mcp-rando-server

Anmeldung (Google) und Freigaben

Seit Version 2 ist alles nur noch für freigegebene Google-Konten erreichbar:

• MCP (/mcp) nutzt OAuth 2.1: Beim Verbinden öffnet der Client (z. B. Claude) ein Fenster, man bestätigt den Zugriff, meldet sich mit Google an und bekommt ein Token. Danach läuft alles ohne erneute Anmeldung.

• Demo-Seite und REST verlangen eine Google-Anmeldung im Browser (Sitzung 7 Tage, /logout meldet ab).

Prinzip: Google sagt, wer jemand ist (Authentifizierung), der Worker entscheidet, ob er darf (Autorisierung). Die Freigabeliste wird beim Anmelden und bei jedem Aufruf geprüft – wer gestrichen wird, ist sofort draußen. Im Protokoll steht jetzt zu jedem Aufruf die E-Mail-Adresse (nutzer), dazu [auth] angemeldet/abgelehnt: ….

Code: src/auth.ts (Zustimmungsseite, Google-Anmeldung, Freigabeliste, Browser-Sitzung).

Einrichtung

1. Google-OAuth-Client anlegen – console.cloud.google.com

1. Neues Projekt anlegen, z. B. „random-mcp“.

2. Google Auth Platform (früher „OAuth-Zustimmungsbildschirm“) öffnen und einrichten: App-Name „random-mcp“, Support-E-Mail, Zielgruppe Extern. Unter Zielgruppe bleibt die App im Status Testing; dort stratze@gmail.com als Testnutzer eintragen.

3. Clients → Client erstellen → Typ Webanwendung. Unter Autorisierte Weiterleitungs-URIs beide eintragen:

   • https://random-mcp.stratze.workers.dev/callback (für MCP-Clients)

   • https://random-mcp.stratze.workers.dev/login/callback (für den Browser)

4. Client-ID und Clientschlüssel kopieren.

2. Secrets in Cloudflare hinterlegen – Worker random-mcp → Settings → Variables and Secrets → Add, jeweils Typ Secret:

Solange eins fehlt, kommt niemand rein (die Seiten sagen dann, was fehlt). Den Speicher für Anmeldedaten (KV OAUTH_KV) legt Cloudflare beim Deploy automatisch an.

3. Connector neu verbinden – in Claude den bisherigen Connector entfernen und mit derselben URL neu hinzufügen. Die Anmeldung wird automatisch erkannt; „Sign in now“ wählen.

Freigaben ändern: nur das Secret ERLAUBTE_NUTZER bearbeiten – kein Code, kein Neuverbinden nötig. (Solange die Google-App im Status „Testing“ ist, muss ein neues Konto zusätzlich dort als Testnutzer stehen.)

Lokal testen: Datei .dev.vars mit den drei Werten anlegen (wird nicht eingecheckt), dann npm run dev.

REST-API

Alle Aufrufe sind GET, die Antwort ist JSON. Nötig ist eine Browser-Anmeldung (sonst 401 mit Hinweis auf /login). Listen werden kommagetrennt übergeben.

/api listet alle Werkzeuge. Fehler kommen mit Status 400 und Feld fehler zurück.

Demo: langsamer Dienst (~30 Sekunden)

Zeigt, wie man Nutzer bei langen Wartezeiten bei Laune hält – komplett mit MCP. Die Zufallszahl selbst ist echt, nur die Wartezeit ist gespielt.

Wann welches Muster?

• Fortschrittsmeldungen zeigt nicht jeder Client an, und manche brechen lange Aufrufe ab. Das blockierende Muster ist daher gut zum Vorführen, aber riskant im Alltag.

• Das Auftragsmuster funktioniert mit jedem Client: Das LLM sagt dem Nutzer die Dauer, fragt in Abständen nach und schreibt zwischendurch Zwischenmeldungen – der Nutzer sieht so die ganze Zeit, dass etwas passiert.

REST: /api/auftrag_starten?minimum=1&maximum=100&dauer_sekunden=30 → /api/auftrag_status?id=<auftrag_id>. Auf der Demo-Seite gibt es dafür den Knopf „🐢 Langsamer Dienst“ mit Fortschrittsbalken.

Technik: Ohne Datenbank – Startzeit, Bereich und eine zufällige Kennung stecken in der Auftrags-ID, das Ergebnis wird daraus abgeleitet (für eine Demo okay; wer die ID kennt, könnte das Ergebnis vorab ausrechnen).

Protokoll / Debugging

Jeder Aufruf wird als JSON-Zeile protokolliert:

• typ: "mcp-anfrage" – jede MCP-Nachricht: Methode (initialize, tools/list, tools/call), Werkzeug, Argumente, bei initialize auch Name und Version des Clients

• typ: "werkzeug" – jede Ausführung über MCP oder REST (kanal): Eingabe, Ergebnis oder Fehler, Dauer

Zu jedem Eintrag: Zeit, Anfrage-ID (Cloudflare-Ray-ID), IP, Land, Stadt und User-Agent des Aufrufers.

Ansehen: Cloudflare-Dashboard → Workers & Pages → random-mcp → Logs (gespeichert, filterbar). Live mitlesen: npx wrangler tail random-mcp.

Zum „Wer“: Ruft Claude über einen Connector auf, kommt die Anfrage von Anthropics Servern – IP und User-Agent zeigen also „Claude“. Wer dahinter steckt, steht im Feld nutzer (die angemeldete Google-Adresse).

Projektaufbau

src/server.ts     Zufallskern, Werkzeuge, MCP, REST, Demo-Seite, Protokoll
src/auth.ts       Anmeldung (OAuth/Google), Freigabeliste, Browser-Sitzung
wrangler.jsonc    Cloudflare-Konfiguration (Name des Workers)
package.json      Abhängigkeiten

Ein neues Werkzeug: Logik in WERKZEUGE eintragen, in createServer() für MCP anmelden, in restAufruf() die URL-Parameter zuordnen.

Veröffentlichen (ohne lokale Installation)

1. Dieses Projekt in ein neues GitHub-Repository hochladen.

2. Im Cloudflare-Dashboard unter Workers & Pages einen neuen Worker anlegen und dabei das GitHub-Repository importieren. Cloudflare baut und veröffentlicht den Worker; jede Änderung im Repository wird automatisch neu veröffentlicht.

3. Die Adresse lautet dann https://random-mcp.<dein-konto>.workers.dev. Aufruf im Browser zeigt „random-mcp läuft“.

4. In claude.ai unter den Einstellungen einen eigenen Connector hinzufügen mit der URL https://random-mcp.<dein-konto>.workers.dev/mcp. Danach steht er auch in der Handy-App zur Verfügung.

Alternativ per Kommandozeile (Node.js nötig): npm install, npx wrangler login, npm run deploy. Lokal testen: npm run dev → http://localhost:8787/mcp.

Roadmap

• Stufe 1: Cloudflare-Zufall (crypto.getRandomValues), 5 Werkzeuge, öffentlich über Cloudflare Worker

• REST-API, Demo-Seite und Protokoll aller Aufrufe

• Demo „langsamer Dienst“: Fortschrittsmeldungen und Auftragsmuster

• Zugriffsschutz: Google-Anmeldung (OAuth 2.1 für MCP, Sitzung für Browser) mit Freigabeliste

• Stufe 2: random.org als Quelle (atmosphärisches Rauschen)

  • kostenloser Developer-Schlüssel von api.random.org (max. 1.000 Anfragen/Tag, für Entwicklung/Test gedacht)

  • Schlüssel als Cloudflare-Secret hinterlegen (RANDOM_ORG_API_KEY), nicht im Code

  • Parameter quelle für die Werkzeuge; automatischer Rückfall auf Cloudflare-Zufall bei Fehler oder leerem Kontingent

• Vorrat (Pool) für langsame Quellen: im Hintergrund per Cron auffüllen, Aufrufe antworten sofort

• Ideen für später

  • weitere Werkzeuge, z. B. Passwort- oder Namensgenerator, Teams auslosen, Glücksrad

  • Quantenzufall (ANU) als weitere Quelle prüfen