TheSEO

theseo-mcp

Open-source remote MCP-server van TheSEO, instituut voor zichtbaarheid. Voor zover wij hebben kunnen nagaan de eerste MCP-server van een Nederlands marketingbureau.

MCP (Model Context Protocol) is de open standaard waarmee AI-assistenten zoals Claude externe tools kunnen gebruiken. Voeg deze server één keer toe en je AI kan zelf een SEO-scan draaien, lokale vindbaarheid checken, gratis Claude-skills opzoeken, het bedrijfsbrein-sjabloon ophalen en onze eigen AI-Index bevragen. Alles wat deze server aanbiedt is gratis en vraagt geen account.

De server draait als Cloudflare Worker met Streamable HTTP transport.

Endpoint: https://mcp.theseo.nl/mcp

Op mcp.theseo.nl draaien deze tools samen met de tools van het TheSEO-platform: de AI-zichtbaarheid per model (ai_zichtbaarheid_merk), de gat-analyse per branche (ai_index_gat), de AI-crawlercheck (ai_crawler_check), Nederlandse vakregels met bron (vakregels) en, met een account, geheugen, taken en premium skills. Uitleg en installatie: mcp.theseo.nl. seo_scan en lokale_vindbaarheid_check staan daar voorlopig uit, omdat de siteflow erachter nog een lead bewaart; ze werken wel op de losse server https://theseo-mcp.sales-cc8.workers.dev/mcp.

De zeven tools in deze repo

1. seo_scan

Scant een URL op 24 SEO-punten in vier categorieën: techniek, on-page, content en AI-gereedheid. Dit is dezelfde scanner als de gratis SEO-scan op theseo.nl.

Voorbeeld-aanroep:

"Draai een SEO-scan op https://voorbeeld.nl en vat de grootste problemen samen."

{ "url": "https://voorbeeld.nl" }

Je krijgt per categorie een score (0 tot 100) en per punt een eerlijke uitleg van wat er goed of mis is.

2. lokale_vindbaarheid_check

Controleert hoe vindbaar een bedrijf is in Google Maps: bestaat er een Google Bedrijfsprofiel, en zijn openingstijden, foto's, beoordeling, reviews, website en telefoonnummer op orde. Dezelfde check als de lokale vindbaarheidschecker.

Voorbeeld-aanroep:

"Check de lokale vindbaarheid van Bakkerij Jansen in Utrecht."

{ "bedrijfsnaam": "Bakkerij Jansen", "stad": "Utrecht" }

De score telt alleen mee wat werkelijk gemeten is. Wat niet meetbaar is komt terug als niet gemeten, nooit als onvoldoende.

3. skill_zoeken

Doorzoekt de volledige catalogus van gratis Nederlandstalige Claude-skills van theseo.nl op onderwerp. Per treffer krijg je de naam, de beschrijving, de uitlegpagina en de directe download-URL van de zip.

De catalogus bevat twee soorten skills. De denk-, schrijf- en coachskills van de skills-hub, en de vakskills die bij een artikel horen: lokale SEO per beroep, linkbuilding, WordPress en Google Ads. Het exacte aantal staat in src/catalogus.json onder aantal, met de verdeling in aantal_hub en aantal_artikel.

Voorbeeld-aanroep:

"Is er een gratis skill die me helpt met een SWOT-analyse?"

{ "onderwerp": "swot analyse", "max": 5 }

4. bedrijfsbrein_template

Geeft de volledige inhoud van het gratis bedrijfsbrein-sjabloon terug: een invulbaar bedrijfsbrein.md contextbestand dat een AI leert wie je bedrijf is. Handig om het sjabloon direct in een gesprek te laten invullen.

Voorbeeld-aanroep:

"Haal het bedrijfsbrein-sjabloon op en vul het in voor mijn schildersbedrijf."

Deze tool heeft geen parameters.

5. ai_index_branche

Geeft per branche wat onze eigen AI-Index gemeten heeft: het aantal geldige metingen, de weigeringen met de letterlijke reden van het model, de tien meest genoemde bedrijven en hoe geconcentreerd het beeld is.

{ "branche": "logistiek" }

6. ai_index_vragen

Geeft de letterlijke vragen die wij aan het model stellen voor een branche, plus de meetmethode. Daarmee kun je de meting zelf naspelen.

{ "branche": "horeca", "max": 5 }

7. ai_index_bedrijf

Zoekt of een bedrijfsnaam voorkomt in de metingen, en zo ja in welke branches en bij welke vragen. Komt een naam er niet in voor, dan zegt de tool dat het uitdrukkelijk geen oordeel is: het is een steekproef met een vaste vragenlijst.

{ "bedrijfsnaam": "bol.com" }

Alle drie eindigen met dezelfde bronregel: het model, het aantal metingen, de laatste meetdatum, de licentie CC BY 4.0 en de link naar de volledige bijsluiter. Geen trends over de tijd en geen uitspraken over bezoekersaantallen: de metingen zijn met temperature 1 gedaan, dus verschillen tussen momenten zijn ook samplingruis.

Installatie

Claude (claude.ai en de desktop-app)

1. Ga naar Instellingen, dan Connectors.
2. Kies Connector toevoegen en plak de URL: https://mcp.theseo.nl/mcp
3. Klaar. Vraag Claude bijvoorbeeld om een SEO-scan van je site.

Claude Code

claude mcp add --transport http theseo https://mcp.theseo.nl/mcp

Cursor

Voeg toe aan ~/.cursor/mcp.json (of .cursor/mcp.json in je project):

{
  "mcpServers": {
    "theseo-mcp": {
      "url": "https://mcp.theseo.nl/mcp"
    }
  }
}

Eerlijke grenzen

• De SEO-scan bekijkt één pagina op 24 automatisch meetbare punten. Het is een goede eerste indruk, geen volledige audit. Een echte audit kijkt naar meerdere pagina's, concurrentie, zoekwoorden en zoekintentie, en dat blijft handwerk.
• De vindbaarheidscheck meet wat via de Google Places API meetbaar is. Criteria die niet meetbaar zijn (zoals de positie in het lokale kaartblok zonder live zoekopdracht) worden expliciet als niet gemeten teruggegeven en tellen niet mee in de score.
• De check werkt pas als de bijbehorende API-sleutel op de TheSEO server staat. Ontbreekt die, dan krijg je het eerlijke foutbericht van de API te zien in plaats van een verzonnen resultaat.
• De skill-catalogus is een momentopname die met de site meegenereerd wordt. Nieuwe skills verschijnen na een nieuwe deploy van deze server.

Wat er bewaard wordt

• Deze server heeft geen database, geen accounts en geen inlog.
• Per tool-aanroep schrijft hij één telpunt naar Cloudflare Analytics Engine (dataset theseo_mcp_tool_usage): de toolnaam, de UTC-dag en het getal 1. Geen invoer, geen IP-adres, geen headers en geen gesprekstekst. Zo zien we welke tools gebruikt worden, niet door wie.
• seo_scan en lokale_vindbaarheid_check sturen je invoer door naar de site-Worker van theseo.nl, met de kop X-TheSEO-Kanaal: mcp, zodat de site ziet dat de aanroep via MCP kwam. Die siteflow bewaart nu het gescande webadres, of de bedrijfsnaam en plaats, samen met de uitslag als lead in het CRM van TheSEO, net als het formulier op de site. Daarom staat bij deze twee tools readOnlyHint: false.
• De andere vijf tools lezen alleen gegevens die in de server zijn ingebakken en sturen niets door.
• De Worker-logs bevatten alleen eigen foutmeldingen zonder invoer; de standaard aanroeplogs van Cloudflare staan uit (invocation_logs: false in wrangler.jsonc).

Zelf draaien of meebouwen

Vereist Node 20 of nieuwer.

npm install
npm test              # alle tests, in-process en zonder netwerk
npm run dev           # lokaal op http://localhost:8787/mcp
npm run check         # TypeScript-controle
npm run dry-run       # controleer de deploy zonder te deployen
npm run deploy        # deploy naar Cloudflare (eigen account nodig)

De skill-catalogus (src/catalogus.json) en het bedrijfsbrein-sjabloon (src/bedrijfsbrein.json) worden gegenereerd uit de site-repo van theseo.nl:

npm run genereer-catalogus -- /pad/naar/theseo-cloudflare-site

Het script leest twee bronnen: de skills-hub en alle overige HTML in public/. Een zip die op schijf staat maar nergens op de site gelinkt is blijft er bewust buiten, want dan is hij nog niet uitgegeven.

Onderhoudsregel. Wie een skill-zip aan de site toevoegt, synct dezelfde dag drie dingen: de site zelf, de GitHub-repo claude-skills-nederlands, en deze catalogus. Ging dat mis, dan bestaat de skill wel als download maar vindt skill_zoeken hem niet. Dat is precies wat er tussen 11 en 18 augustus 2026 gebeurde: de catalogus las alleen de skills-hub en miste daardoor elke vakskill die bij een artikel hoort. Volgorde: catalogus genereren, npm test, npm run check, npm run deploy, daarna committen en pushen. Genereer altijd vlak voor de deploy, niet een dag ervoor; er komen regelmatig skills bij.

Premium skills komen nooit in deze publieke catalogus. Het script slaat pagina's onder /skills/premium/ over en stopt met een foutmelding, zonder iets weg te schrijven, zodra een regel premium lijkt: een pagina onder /skills/premium/, het woord premium als deel van de slug, een downloadlink die afwijkt van /assets/skills/<slug>.zip of een premium toolnaam. De test test/catalogus-premium.test.ts controleert hetzelfde op de ingebakken catalogus en op het script zelf.

Het script stopt ook met een foutmelding als het op de skills-hub geen enkele skill vindt. Dat is geen overdreven voorzichtigheid: toen die pagina in augustus 2026 werd herbouwd naar een doorzoekbaar tegelraster, vond het oude patroon niets meer en schreef het script zonder klagen een catalogus zonder clusterlabels weg. Loopt het script daarop vast, pas dan de patronen in doorgang 1 aan.

De server zelf bevat geen secrets. De scan- en checklogica draait op de site-Worker van theseo.nl; deze MCP-server roept alleen de publieke endpoints daarvan aan.

Gebruiken als bibliotheek

De zeven tools zijn ook als functie te gebruiken, zodat een andere Worker ze in zijn eigen MCP-server kan zetten, naast eigen tools. Het pakket exporteert registreerGratisTools(server, deps):

import { McpServer } from '@modelcontextprotocol/server';
import { maakGebruiksteller, registreerGratisTools } from 'theseo-mcp';

const server = new McpServer({ name: 'mijn-server', version: '1.0.0' });
registreerGratisTools(server, {
  site: env.SITE_WORKER, // service binding naar de site-Worker
  teller: maakGebruiksteller(env.MCP_USAGE), // optioneel
});

• Er is geen globale binding: alles gaat via deps. Een onbekende of verkeerde sleutel in deps geeft direct een TypeError.
• Elke aanroep naar de site draagt de kop X-TheSEO-Kanaal: mcp. Wil je extra koppen meesturen, zoals een handtekening, geef dan als site een eigen object met een fetch die ze toevoegt.
• premiumSkills is optioneel: een lijst met slug, naam en zin. Alleen dan toont skill_zoeken die namen ook, gemarkeerd als premium en zonder download. Laat de lijst leeg voor anonieme gebruikers. Deze repo bevat zelf geen enkele premium skill; valideerPremiumSkills controleert de lijst.
• zod 4.4.3 en @modelcontextprotocol/server 2.0.0 zijn peerDependencies met een vaste versie. De gebruikende Worker levert ze, zodat er maar één kopie van zod in de bundel zit.
• Het pakket levert TypeScript-bron en importeert JSON. De gebruikende Worker heeft daarom resolveJsonModule nodig in zijn tsconfig.json; Wrangler en Vitest bundelen de bron zelf.

Techniek

• TypeScript, @modelcontextprotocol/server v2 (de officiële MCP TypeScript SDK)
• agents van Cloudflare voor de stateless Streamable HTTP handler
• Cloudflare Workers, deployment via wrangler
• Tests met de officiële MCP-client tegen de echte handler, in-process en zonder netwerk

Licentie

MIT. Gemaakt door TheSEO. Vragen of ideeën: open een issue.