MisarSEO MCP Server

Content ideas for a seed keyword, composed from three sources this codebase already fetches for other features: the SERP for the seed (titles of pages already ranking for it), PAA-style questions (real autocomplete completions reframed as questions), and autocomplete keyword suggestions. Grouped into topic clusters by shared phrasing, using the same phrase-clustering engine the saved-keyword Topic Clusters feature uses. FREE — none of the three sources is billable in this codebase today. Three real upstream calls per request, so it is rate limited. NOT a Keywords-Explorer-style overlap report: this codebase has no keyword-to-URL index, so `clusters` group the REAL text of three OBSERVED sources rather than a fabricated 'what else these pages rank for'. `coverage.serpUnavailable`/`suggestionsUnavailable` mean that source could not be asked at all — distinct from that source genuinely returning nothing — and one source being unavailable never sinks the other two. Every idea not assigned to a cluster is still returned in `ungrouped`, never discarded.

Observed history for one tracked prompt — one point per real scheduled check (`mentionedByCount`/`citedByCount` out of `successfulModelCount`), oldest first. Empty until checks accumulate; never interpolated or back-filled. FREE — reads recorded checks.

Unlinked brand mentions: searches the free SERP backend for `brand` as a QUERY, then checks whether each result page already links to `trackedDomain`. Free: one SERP fetch plus up to 10 live third-party page fetches, no AI-gateway spend. ALWAYS narrow on `state` first: `serp_unavailable` means no free SERP provider could be reached — never treat it as "zero mentions found". `analysed` carries `candidates[]`, each `status: "linked" | "unlinked" | "unreachable"`. Bounded by SERP result count (the first page or two of free-SERP results), never an exhaustive web crawl or a full content index — the Common Crawl-based version of this gap is a decided wont-fix; `scopeNote` states this on every response. `candidates[].platform` reuses the AI-citation platform classification (YouTube/TikTok/Reddit/Wikipedia/LinkedIn/Quora, or null) at no extra cost.

Plan tier, credits remaining, and every quota/count dimension tracked against it for the caller's organization. FREE: reads counters this codebase already maintains for its own gating — nothing here calls a paid provider or spends a credit. `gatingActive` is false on a self-hosted deployment with no billing provider configured: `tier`, `creditsRemaining` and `quotas` are all null there, not a fabricated tier. `counts` (projects/rank-tracked keywords/API keys) is always populated. Inside a quota dimension, `used: null` means NOT TRACKED — an unlimited tier's counter is never incremented in the first place — never a real zero; `used: 0` IS a real measured zero. `aiGatewayOps` is the shared platform AI-gateway key's own monthly ceiling, reported separately because it is a platform-abuse ceiling, not a plan entitlement.

Device/browser/OS breakdown for a project's own tracking snippet. Every field is derived server-side from the visitor's User-Agent header at collection time. FREE, first-party.

Referrer/channel/UTM breakdown for a project's own tracking snippet, including AI referral attribution: aiReferral.bySource breaks the ai-referral channel out by assistant (chatgpt/claude/perplexity/gemini/copilot/you/poe). aiReferral.undercountNote is not decoration — industry measurement puts a large share of real AI-assistant referrals arriving with no referrer header at all, landing in the direct channel instead. This number is a measurable floor, never a complete count. FREE, first-party.

Sessions/pageviews/bounce-rate time series for a project's own tracking snippet. FREE — first-party data collected by MisarSEO's own snippet (/api/analytics/snippet.js), never a paid or rate-limited third-party call. `totals.bounceRate` is null (not 0) when there were no sessions in the range.

Top pages by view count, plus separate entry-page and exit-page breakdowns, for a project's own tracking snippet. FREE, first-party.

Yandex's own view of a project's domain: the indexing summary — including the Site Quality Index (SQI), a third independent authority signal alongside OpenPageRank and Tranco — and popular search queries, read straight from the Yandex Webmaster API. FREE (no credits). Bring-your-own-token: requires the deployment operator to set YANDEX_WEBMASTER_OAUTH_TOKEN (one token covers every host verified on that Yandex account — no per-project connect step, and MisarSEO never drives the OAuth flow itself). Answers { ok: false, reason: 'not_configured' } when unset, or 'no_matching_host' when the project's domain has no verified match on the account. Yandex publishes no backlink-lookup endpoint at all, so unlike get_bing_site_overview this has no backlinks section. `diagnostics` lists individually named issues (e.g. NO_SITEMAPS, DNS_ERROR) that `summary.siteProblems` only counts by severity.

Link Building Tool: bulk-add up to 500 prospects at once from already-parsed rows (each with at least a domain). FREE (no credits), but this is a MUTATION. One bad or duplicate row never aborts the rest — the response reports added/duplicates/errors per row.

Run Google Search Console's URL Inspection on up to 10 URLs of the connected property: index/coverage state, last crawl time, Google-selected vs declared canonical, and mobile/rich-results verdicts. Use it to answer 'is this page indexed? why not?'. Read-only and FREE (no credits) — Search Console is first-party data and meters nothing. Every submitted URL comes back as a row, but a row carrying `error` was NOT inspected: Google refused or failed on it, so its index state was not measured rather than found to be bad. Count the rows without an `error` when saying how many URLs you checked. A verdict of UNKNOWN is Google's own 'no determination', not a page that is missing from the index.

Every Rank Tracker AND Site Audit project the caller's connected Ahrefs Connect grant can access — the data source for picking which project(s) to bind to a MisarSEO project (see set_ahrefs_project). Live call to the Ahrefs API v3 under the caller's OWN OAuth token. Read-only and FREE (no credits). Check `requiresReconnect` before treating both lists as 'no projects': true means the stored grant can no longer reach Ahrefs.

Every site the caller's connected Bing Webmaster OAuth grant can access — the data source for picking which site to bind to a project (see set_bing_site). Live call to the Bing Webmaster API (GetUserSites) under the caller's OWN OAuth token, not the operator key. Read-only and FREE (no credits). Check `requiresReconnect` before treating an empty `sites` list as 'no sites': true means the stored grant can no longer reach Bing Webmaster.

Lists a project's brand monitors — targets re-scanned by Brand Radar on a schedule rather than only when run_brand_radar_scan is called. FREE: database only, no credits spent.

Competitor page change detection: the specific competitor URLs monitored for a project, with `lastCheckedAt` (null until the first scheduled check reaches it). FREE — database only, no credits spent. Use get_competitor_monitor_changes for the actual detected-change timeline of one URL.

Disavow file management: every disavow entry for a project, oldest first. FREE (no credits). Use export_disavow_file to get the actual Google-format .txt content.

Every GA4 property the caller's connected Google Analytics grant can access — the data source for picking which property to bind to a project (see set_ga4_property). Live call to the Analytics Admin API (accountSummaries.list), not an archive read. Read-only and FREE (no credits). Check `requiresReconnect` before treating an empty `properties` list as 'no properties': true means the stored grant can no longer reach Google Analytics.

Every Google Business Profile account and location this deployment's operator credential can manage — the picker data for set_gbp_connection. Not project-scoped data (the answer does not depend on the project passed; projectId only satisfies the ownership check). Returns `{ accounts: [{ name, accountName, locations: [...] }] }`. Live Google API calls.

Posts published on the project's linked Google Business Profile location. A 404 means no location is linked — use set_gbp_connection first.

Link Building Tool: a prospect's activity log — every manually-typed note plus every auto-recorded status change, newest first. FREE (no credits).

Link Building Tool: every prospect for a project, newest first, each enriched with a LIVE domain-authority read (never cached, never an invented score). FREE (no credits). White-hat scope: research + outreach assistance only.

Patches: every issue type this project auto-publishes a freshly AI-drafted patch for, immediately on draft (capped at 20 auto-publishes per project per day). FREE (no credits), read-only.

Patches: every title/metaDescription/canonical/redirect fix drafted for a project, newest first, one active row per (page, field). FREE (no credits), read-only.

Lists the caller organization's portfolios, each carrying `projectCount`. FREE: database only, no SEO data provider is called and no credits are spent.

Lists the active projects in the user's organization. FREE — database only, charges no credits. Use this whenever you need a `projectId` for another MisarSEO tool. Returns `{id, name, domain, url}` per project; pass the `id` value as `projectId`. `domain` is null for a project that has never had one set, which is not a missing lookup — get_keyword_gap and get_link_intersect read the project's own domain from this record and refuse to run without it. Archived projects are not listed.

Chart notes on a rank tracker's own timeline — 'deployed new title tags', 'algorithm update' — oldest first. FREE: database only, no SEO data provider is called and no credits are spent. Config-level, not per-keyword or per-device: a deploy or algorithm change is a fact about the date, not about any one reading.

Tracked keywords whose latest ranking URL is not the target URL you declared for them (see set_rank_keyword_target_url). FREE: database only, no SEO data provider is called and no credits are spent. NOT the same detector as get_cannibalisation_report (Search Console-based), which finds two-or-more of the site's OWN pages splitting Search Console impressions for one query. A rank check records only the single best-ranking URL per keyword per run, so this can only tell you the winning page was not the one you intended — not that a second own page also appeared in the SERP.

Lists the tags in use on one rank tracker, plus the project's whole tag vocabulary. Use it to find tag IDs before calling update_rank_keyword_tag, and to see how a tracker with hundreds of keywords is already organised. FREE: database only. No SEO data provider is called and no credits are spent, so it is safe to call as often as needed. The two lists mean different things and are deliberately separate. `tagsInUse` is what THIS tracker's keywords actually carry, and its `keywordCount` counts TRACKED keywords carrying the tag — not the saved-keyword count the same tag carries elsewhere, which would never match the rows it filters. It is empty for a tracker that has never used a tag. `projectTags` is the project's full vocabulary including tags unused here, so a tag can be reused rather than re-coined. The vocabulary is the project's EXISTING saved-keyword tags: one namespace shared with the saved-keyword list, not a second set.

Lists the keywords tracked by ONE rank tracker: `{ keywords, totalCount, page, pageSize }`, each row `{ id, configId, keyword, searchVolume, keywordDifficulty, cpc, metricsFetchedAt, createdAt }`. It returns NO positions and runs no check — read positions with get_rank_tracker. The row `id` is the tracking-keyword ID that remove_rank_tracking_keywords, update_rank_keyword_tag and set_rank_keyword_target_url take. FREE: database only.

Lists a project's report definitions, each carrying `widgetCount`. FREE: database only, no SEO data provider is called and no credits are spent.

Lists keywords saved to a project, with whatever metrics have been cached for them (search volume, difficulty, CPC) and their tags. FREE — reads MisarSEO's own database, runs no provider lookup and charges no credits. Filter by keyword text with `search`; page through with `page` and `limit` (50, 100 or 250 rows per page — any other value is rounded down to one of those), ordered by `sort`/`order`. A metric is null when nothing has ever fetched it for that keyword — saving a keyword does not measure it. Null is not zero volume and not zero difficulty; run research_keywords to fill them. `totalCount` is how many keywords match the filter, and `rows` is only the current page of them, so report both.

Lists a project's tracked prompts — prompts re-run through explore_ai_prompt's real answer pipeline on a schedule and diffed against the previous check for mention/citation drops. FREE: database only, no credits spent.

Every host the caller's connected Yandex Webmaster OAuth grant can access — the data source for picking which host to bind to a project (see set_yandex_host). Read-only and FREE (no credits). Check `requiresReconnect` before treating an empty `hosts` list as 'no hosts': true means the stored grant can no longer reach Yandex Webmaster.

Bot hit counts per (day, bot category, bot label, status code, content-type bucket) across every log upload in the date range — powers a time-series, status-code, or content-type view of bot traffic. Rows are `{ day, botCategory, botLabel, statusCode, contentType, hitCount }`; botCategory is ai_crawler/search_engine/other_bot. Dates are ISO (YYYY-MM-DD), UTC. An empty result means nothing was measured in the range — no bot hits were recorded from the logs uploaded for those days, which is not the same as no bots visiting. FREE (no credits).

A project's server-log uploads and their parse status — the Log File Analyzer / Bot Analytics feature. Each row is `{ id, fileName, sizeBytes, status, lineCount, parsedLineCount, skippedLineCount, errorMessage, createdAt, completedAt }`. `status` is one of queued/parsing/completed/failed. lineCount/parsedLineCount/skippedLineCount are null until parsing completes — an absent count is not zero. FREE (no credits). Pair with log_analyzer_upload to add a log, log_analyzer_daily_summary / log_analyzer_top_paths for the report.

The paths bots hit most, per (bot category, bot label, path, status code) — the busiest-paths table of Bot Analytics. Rows are `{ botCategory, botLabel, path, statusCode, hitCount, lastSeenAt }`, ordered by hitCount descending, capped at 200. Optionally filter to one bot category (ai_crawler/search_engine/other_bot). An empty result means nothing was measured — no bot path hits were recorded from uploaded logs. FREE (no credits).

Upload a server access log for background parsing (Log File Analyzer / Bot Analytics). Only Apache/Nginx Combined Log Format text is supported. Pass the raw log text in `content`; parsing runs in the background, so this returns once the upload is stored, before it is fully processed — poll log_analyzer_list_uploads for status. Requires the `admin` role. Plan-tier gated: the deployment's tier caps lines processed per upload and uploads per month. Practical limit: tool calls carrying megabytes of text are impractical — prefer the web UI for large logs. FREE (no credits).

Patches: makes a drafted fix live — visible in the project's public manifest, which the embedded snippet (or, for redirects, an operator-deployed Worker) reads from the visitor's browser. The audited site's own origin content is never touched. FREE (no credits), but this is a MUTATION. Requires an org admin.

Asks Yandex Webmaster to re-crawl one specific URL on a project's matched host. FREE (no credits), but this is a MUTATION — unlike get_yandex_site_overview, it queues real work on the operator's live Yandex Webmaster account and spends that account's daily recrawl quota. Bring-your-own-token: requires YANDEX_WEBMASTER_OAUTH_TOKEN. Answers { ok: false, reason: 'not_configured' } when unset, or 'no_matching_host' when the project's domain has no verified match on the account. Yandex's own documented failure cases — the URL already queued, or the account's recrawl quota already spent — surface as a normal tool error, not a 200 with ok:false.

Stops monitoring one competitor URL. Its historical snapshots and detected changes are deleted along with it (cascading delete) — unlike rank tracking's competitor removal, there is no separate archive kept.

Disavow file management: remove one disavow entry by id (from list_disavow_entries). FREE (no credits), but this is a MUTATION. Succeeds whether or not entryId existed.

Link Building Tool: remove one prospect by id (from list_link_prospects), along with its activity log. FREE (no credits), but this is a MUTATION. Succeeds whether or not prospectId existed.

Removes projects from a portfolio. Succeeds whether or not an id was actually a member. FREE: database only, no SEO data provider is called and no credits are spent.

Removes a chart note from a rank tracker's own timeline. FREE: database only, no SEO data provider is called and no credits are spent. Succeeds whether or not `id` matched an existing note.

Removes keywords from a rank tracker by their tracking-keyword IDs (from list_rank_tracking_keywords). The keywords stop being checked; their past position snapshots are deliberately kept, so history survives. FREE: database only.

Renames a portfolio. FREE: database only, no SEO data provider is called and no credits are spent.

Renames a report definition. FREE: database only, no SEO data provider is called and no credits are spent.

Renders a report definition — fetches ONLY its selected widgets, not a fixed set. FREE: every widget is a local Postgres read, no upstream call, so this never spends a paid-provider credit or a live Search Console quota unit. `rank_volatility` and `share_of_voice` read the project's FIRST active rank tracker only; `rank_movers` sums across every active tracker.

Reply to (or overwrite the reply on) one review, by reviewId from get_gbp_reviews. Google's endpoint has no separate create/update — this always overwrites. Publishes immediately; there is no draft/preview step.

Turns a seed topic into candidate prompts worth tracking (real Google/Bing autocomplete completions reframed as questions) plus observed mention-rate signals from this project's own already-tracked prompts. This is NOT prompt search volume — no honest corpus of 'how many people ask this' exists anywhere this codebase can reach, so no volume or difficulty number is invented. FREE: no AI-gateway budget, no paid-plan gate, no credits spent.