Kleap MCP Server

Delete the rows matching where (required, non-empty, exact matches, e.g. {"id":42}). Permanent. Returns how many were deleted.

The app's Kleap Database (Postgres): its tables, row counts and columns. Call it before reading or writing rows. provisioned:false means the app has no database yet — create one with modify_app (describe the data to store).

Read rows from one table of the app's database. where = exact matches, e.g. {"status":"new"}. Max 500 rows per call; page with offset while has_more is true.

Run SQL on the app's database (owner-level, needs database:write), values as $1, $2 in params. Rows capped at 500 / 5 MB. A table left without row-level security is rolled back (RLS_REQUIRED). To just read rows, prefer query_database_rows.

Update the rows matching where (required, non-empty, exact matches, e.g. {"id":42}) with the values in set. Returns the updated rows.

Use this when the user wants a complete, hosted website or web app built from a text description (e.g. 'build me a website for X'). Kleap's AI builds AND auto-deploys the whole site; this takes a few minutes (typically 5 to 15 min). Returns a build_url instantly so the user can watch it build live. In a widget client (ChatGPT Apps) the preview above shows real-time progress and reveals the final live URL by itself, so you do NOT need to block or keep polling check_task. With NO widget (CLI, script, scheduled or one-shot run) nobody sees that preview and the site does not exist yet: call check_task with the returned task_id about every 30 seconds and stop only on completed (deployment_status deployed) or failed, then get_app for the live URL. Prefer this over write_files for full-site creation.

Resolve a website the user refers to by its ADDRESS — a custom domain ('mysite.ch'), a kleap.io URL ('mysite.kleap.io'), or a slug — to its app_id. Use this FIRST whenever the user names a site by its address instead of an app_id (e.g. 'edit mysite.ch'), then pass the returned app_id to get_app / modify_app / publish_app. ADDRESS TO SHOW THE USER: site_url. When the owner has connected a domain, custom_domain is set and site_url is that domain — say THAT, never the {slug}.kleap.io host, which is the internal address they did not choose.

Show a website to the user: its screenshot, name and live address. This is the ONE tool that renders the finished-site card, so call it once after a build or edit has finished and deployed (check_task says deployment_status deployed) — that is what lets the user SEE what was built. Also use it for plain details: name, slug, URLs, creation date, status, published_at (when the live version went up, null = never published) and has_unpublished_changes (true = some file was edited after the last publish, so publish_app would ship it; call this BEFORE publishing work you did not write; a file deleted since the last publish is not detected; null = cannot be told for a legacy Next.js app). ADDRESS TO SHOW: site_url. If custom_domain is set, the owner connected that domain and it IS their site's address — never hand them the {slug}.kleap.io host instead, they did not choose it. Never call this while a build is still running: it would show the previous version as if it were the new one.

List the source file PATHS of an app (names only, no contents). See the project structure, then read_files to get contents before editing. Astro: src/pages/*.astro, src/data/*.json, src/components/*.astro, public/*.

Remove pages, components or assets from a site — the counterpart to write_files. Use it when a page should no longer exist: a wrong route, a duplicate, an outdated landing page, an image nobody references. Do NOT overwrite the file with empty content instead: that leaves a URL answering 200 with nothing, which is worse for SEO than a clean 404. Deleting a binary also removes its stored bytes. Paths Kleap owns (astro.config.mjs, package.json, tsconfig.json…) are refused — the build lays its own copy back down, so removing them changes nothing. The homepage (src/pages/index.astro) is refused too: a site with no homepage is broken — write a new one instead, writing replaces it. Returns which paths were actually deleted and which did not exist. The pages STAY LIVE until you call publish_app.

Read existing file contents so you can edit them SAFELY instead of rewriting blind (which risks breaking shared components/homepages). Loop: list_app_files → read_files → edit_files (change just the lines that must change) → publish_app; use write_files instead only when you are writing a whole new file. Use it to fix headers/footers, wrong phone numbers, broken links, dead forms. Works with a Read-only key. Returns { files: [{ path, content, type, bytes, truncated?, returned_bytes? }], missing }. Text is capped at 256 KiB per file and 1 MiB per call; truncated files are explicitly marked, and files beyond the call budget must be read separately.

Write WHOLE files DIRECTLY — YOUR model generates the code, Kleap stores, builds and deploys it as-is. To change something in a file that ALREADY EXISTS, use edit_files instead (read_files → edit_files): it replaces just the lines you name, while write_files makes you retype the entire file and silently drops whatever you leave out — on a 30KB shared layout that is how headers and footers get wiped. No Kleap-AI step, so what ships is byte-for-byte what you wrote — the right choice when a phrase, a URL or a schema must be exact. Publishing still audits the result (see publish_app). Best for scaffolding exact pages/components — e.g. programmatic-SEO routes. Astro paths (src/pages/*.astro, src/data/*.json, src/components/*.astro, public/*). Overwrites by path. NPM PACKAGES: do not write package.json (the build replaces it) — the build installs whatever your code IMPORTS, so `import { jsPDF } from "jspdf";` is all it takes. Supported on import: @tiptap/*, jspdf, pdf-lib, html2canvas, papaparse, file-saver, jszip, @ffmpeg/*, howler, wavesurfer.js, browser-image-compression, react-dropzone, recharts, chart.js, d3, @tanstack/*, react-hook-form, three, @react-three/*, leaflet, maplibre-gl, gsap, framer-motion, zustand, date-fns, react-markdown, axios, socket.io-client, radix-ui/*, next-themes, lucide-react, @tabler/*, openai, @ai-sdk/*; anything else is refused at build with a message naming it. A client-side router is never the answer — a route is a FILE (src/pages/about.astro → /about). IMAGES AND BINARIES: set encoding:"base64" on the file and send the bytes — that is how you put a logo, a photo, an OG image, a favicon or a font on the site (png/jpg/webp/svg/ico/mp4/woff2/pdf, 512KB max each decoded). Without it you can only write text, and a site with no images looks unfinished. To ADD an image from a text prompt WITHOUT sending any bytes (a real photo's base64 is too big to emit reliably), use generate_image — Kleap generates it and stores it for you. To REMOVE a page or asset, use delete_files — overwriting it with empty content leaves a URL that answers 200 with nothing, which is worse than a 404. DATA & ACCOUNTS: write_files only STORES files — it cannot provision the Kleap Database, so DB or auth code pushed here has no backend and silently does nothing. Stand the feature up with modify_app first, then edit those pages here. After writing, call publish_app to build & go live.

Connect a domain the user ALREADY OWNS to a live Kleap app (routing + automatic TLS). The app must be live first — a create_app/modify_app with deployment_status deployed already counts as published, so you do NOT need publish_app first. The user points the domain's A record to Kleap. Does not buy anything.

Use this when the user wants to connect (or reconnect) Google Search Console for a site — typically right after get_search_console reported connected:false. Returns a consent_url: give it to the user as a link and ask them to open it and approve access with the Google account that owns the domain in Search Console. That one approval MUST happen in a browser — Google does not allow it any other way, so never claim you can do it for them. Nothing else is needed afterwards: the Search Console property is bound to the site's custom domain automatically, and get_search_console starts answering. If requires_custom_domain is true the site has no custom domain yet: connecting Google would grant access to nothing, so connect a domain first (connect_domain) and publish. Already connected? It returns a consent_url too, but hand that over ONLY to switch Google account; otherwise just read the numbers.

Use this to check whether a website is actually published and live. Returns the published state, the live production URL, and — once a publish has run — the PUBLISH REPORT of what Kleap checked on the site it just built: broken_links (existing pages that fail), dead_nav_links (menu entries pointing at a page that was never written — 90% of real dead links, /contact most often), incoherent_pages (a page answering 200 with content that contradicts the link leading to it), checks (source findings that did NOT block the publish, each with a category and a plain sentence: forms that submit into the void, islands with no client directive so buttons do nothing, broken images, hand-rolled auth or unguarded database access, dead API routes), design_gate (was the rendered homepage looked at), live_verified (was the NEW version confirmed serving), and SEO coverage (JSON-LD pages, sitemap URL count, robots, llms.txt). report.checked:true means the audit RAN, so empty lists mean nothing was found, not that nothing was looked at. If finding_count is above zero, tell the user what was found — in the report's own words, not the rule slugs — and offer to fix it. Do NOT describe a publish as clean when the report lists findings: a site can be live, pretty and still take no leads. status is one of: published, deploying, not_published, unknown_app. Returns the state at THIS instant — report it and end the turn; publishing takes minutes, so calling it repeatedly in one turn only burns the turn.

Use this to take a website LIVE at its public URL. Publishing is VERIFIED-LIVE: the app is only reported published once the new version is provably serving — otherwise it reports 'not confirmed live', never a false 'it is online'. Publishing also AUDITS the built site: every internal link on every page (menu entries to a page never written are the #1 case), pages whose content contradicts the link leading to them, and JSON-LD/sitemap/robots coverage. Most deploys land in under a minute, so this call WAITS a bounded time and returns that `report` here when it does — read it before calling the launch a success, and if it lists findings, FIX THEM (write the missing page, or remove the dead link) before you answer, as you would a build error. On a slower deploy it returns 'publishing' with no report; then do not poll get_publish_status in a loop inside one turn — check once when the user asks again.

Use this when the user asks about traffic, visitors, or which pages/referrers are performing on their PUBLISHED site. Backed by the same analytics as the Kleap dashboard's Visitors view. Returns zeroed data with configured:false if the app has never been published (analytics is set up automatically on publish). Requires the analytics:read scope — sessions connected BEFORE this tool shipped don't have it: on a 403 INSUFFICIENT_SCOPE error, tell the user to disconnect and reconnect the Kleap integration (re-authorize) to grant the scope.

Use this when the user wants to see all their websites with name, slug, preview URL, and production URL.

Start buying a domain: returns a Stripe checkout_url (valid 30 min) that the USER must open and pay. Nothing is bought until they complete checkout — give them the link, never say it is purchased. With app_id it is connected to that app after payment.

Use this when the user asks how their site does IN GOOGLE SEARCH — queries they rank for, impressions, clicks, CTR, average position. Real Search Console data from their own property, not an estimate. Returns totals plus top queries and top pages. It lags ~2 days, so the newest days are always incomplete — say so rather than reporting a drop. If connected is false, call connect_search_console(app_id) — it returns a consent_url to hand the owner, and that IS the whole setup: the property matching the site's domain is bound automatically as soon as they approve. Do NOT send them hunting through Kleap's settings. If site_selected is false the message names the cause — read it, do not guess: the site has no custom domain (connect_domain first — a {slug}.kleap.io host can never be a Search Console property), or the Google account has no VERIFIED property for that domain yet (add and verify it, then read again — Kleap binds it). For all-source visitors use get_analytics. Requires the analytics:read scope — on a 403 INSUFFICIENT_SCOPE error, tell the user to disconnect and reconnect the Kleap integration (re-authorize).

Use this when the user asks how much usage they have left or about their plan status.

Check a domain's connection / DNS status for a Kleap app.

Search for available domains for a site (e.g. 'mybakery'). Returns available names across TLDs. To buy one, call buy_domain — it returns a checkout link the user pays. Use connect_domain for a domain the user already owns.

Change PART of a file without resending it — the counterpart to write_files. Give `old_string` (exact text as in the file today) and `new_string`; Kleap reads, replaces, stores. Nothing else moves. Use it whenever the file exists and only a line, block or URL changes: resending a 30KB layout to fix one line wastes tokens and risks corrupting the rest. read_files first, copy the text EXACTLY. `old_string` must appear once — otherwise the error names the count; add context or pass replace_all:true. Edits are validated together: if any is invalid, nothing is written. Across files the writes are sequential — a late failure names what was already applied. new_string "" deletes the match. Not for new files or binaries. Then publish_app.

Use this when the user asks who filled out their contact form, or wants to see/export leads from their live site. Returns submissions from any <form> built with KleapForm on the app, newest first. Empty list is normal for a brand new site with no visitors yet. Requires the forms:read scope (submissions contain visitor PII) — sessions connected BEFORE this tool shipped don't have it: on a 403 INSUFFICIENT_SCOPE error, tell the user to disconnect and reconnect the Kleap integration (re-authorize) to grant the scope.

Put a REAL photo or illustration on the site by describing it — no image bytes to send. Give a vivid `prompt` and a `public/` `path` (e.g. public/hero.jpg); Kleap generates it with Cloudflare FLUX.2 and stores it as a proper binary asset, exactly like write_files with encoding:"base64" but with NO base64 to transmit (a real image's base64 is too big for a model to emit reliably — this is the ONLY dependable way to add a generated picture). Use it for hero photos, section illustrations, onboarding images, OG images, or to replace a broken/ugly image. Square 768×768 by default; pass width/height (256–1440) for other ratios; hd:true uses the premium model (sharper, slower). ⚠️ To REPLACE an existing image, generate to a NEW filename (e.g. hero-2.jpg) and point the markup at it — overwriting the same path can be served stale from CDN/R2 cache. After it returns, call publish_app to deploy it live.

Insert up to 500 rows into one table of the app's database. Returns the inserted rows (with generated ids/defaults).

Use this when the user wants to change or update an existing website. The AI can overwrite or remove existing content and automatically publishes the result to the live site. This uses Kleap usage. Needs the app_id — if the user named the site by its address (e.g. 'mysite.ch'), call find_app first to get the app_id.

Rename an app's display name. Does NOT change the URL — the live address ({slug}.kleap.io) and any links to it stay intact. (There is no tool to delete the entire app; delete_files removes selected source files.)

Resume a failed or stalled create/modify task from where it stopped — partial files are preserved. Use this when check_task reports 'failed' instead of starting a brand-new create_app. Returns a NEW task_id — poll check_task on that NEW id (not the original). Budget: retry TASK_TIMEOUT/STALE_TASK up to TWICE; retry TASK_FAILED only ONCE; then stop and tell the user. NEVER retry a non-transient error (402 INSUFFICIENT_CREDITS = out of usage, a rejected prompt).

Use this when the user wants to see a visual screenshot of their website. Rate-limited to 1/min per app. The returned image_url is a PNG on the asset host — render it as an image () and nothing else. It is NOT the website's address, so never present it to the user as their site link, and never open, fetch or web-search it: the site's own address is production_url from get_app / find_app.

Free SEO check of ONE public website URL, on Kleap or not (no app_id, no usage consumed, no AI call). Reads up to 12 pages plus sitemap.xml and robots.txt and checks title, meta description, h1, canonical, viewport, lang, og:image, JSON-LD, image alt, thin content, noindex and dead internal links. Returns score.percent out of 100 (a Kleap checklist, not a Google metric), top3 fixes and every finding with its page, impact (1-10) and fix. For a Kleap site apply fixes with read_files, edit_files, publish_app, then run it again.

Check a create/modify task. Returns quickly with the CURRENT status — report it to the user rather than calling again in the same turn; a build takes 5-15 min, so the answer to 'is it ready?' is usually 'still building, here is the progress'. EXCEPTION: in a headless or one-shot run with nobody to answer (CLI, script, scheduled agent), do not stop at 'still building': call it again about every 30 seconds and stop only on completed (deployment_status deployed) or failed. The optional `wait` can shorten the hold but cannot exceed the server cap (8 seconds by default). status is one of: queued, processing, completed, failed, unknown_task (the id is unknown or aged out — that is an answer, not a failure: check the site itself with get_publish_status). On 'completed' the FILES are written; check deployment_status — 'pending' means the site is going live right now and production_url is still the PREVIOUS version, so say 'built, going live' and check once more in about a minute rather than reporting it stuck. 'deployed' means it is genuinely live. On 'failed': TASK_TIMEOUT/STALE_TASK = transient stall → retry_task (returns a NEW task_id to poll); TASK_FAILED = read error.message, retry once. (Running out of usage is not a task failure — create/modify reject up front with 402 INSUFFICIENT_CREDITS.)

Use this when the user wants a paid Kleap plan, runs out of usage, or needs a feature that requires one (custom domain, more usage). Returns an upgrade_url the USER must open and pay — nothing is charged before that, so never say they are subscribed. plan: 'monthly' (default) or 'annual'; 'credits' (legacy name) buys extra usage for users who already have a paid plan. Do not quote a price: the page shows it in the user's currency.

Use this when the user's website preview is sleeping (sandboxes auto-stop after 15 min). Takes ~30-60s to restart.