SEOmatic

NEWCheck out our FREE templates →

A hosted Model Context Protocol server that exposes SEOmatic's tools to any MCP client. Connect interactively over OAuth 2.1, or with a workspace API key as a Bearer token. Tools are consolidated into a small set of outcome tools, each annotated read-only or acting.

Connection

Field	Value
Endpoint	https://app.seomatic.ai/api/mcp
Transport	Streamable HTTP (stateless, POST JSON-RPC 2.0)
Protocol	2025-06-18 (2024-11-05 through 2026-07-28 accepted; newer versions negotiate down)
Server	seomatic v1.0.0
Auth	OAuth 2.1 (interactive clients) or Authorization: Bearer smk_live_...

Install in your assistant (about a minute)

Three steps, same everywhere: open your assistant's connector settings, paste the SEOmatic URL, then log in and pick your site when the SEOmatic screen appears. No API key to copy. After installing, one step people miss: in a NEW chat, open the tools menu in the message box and make sure SEOmatic is enabled for that conversation.

Assistant	Requires	Where to install
Claude (web/desktop)	Paid Claude plan	Settings > Connectors > Add custom connector
ChatGPT	Plus or higher, then enable Developer mode (Settings > Apps > Advanced). The Apps menu only appears on paid plans.	Settings > Connectors > Create
Claude Code / Cursor / Cline	Nothing extra	One command or config entry (below)

Two things that look like problems but are not: the consent screen asks you to log in or create a SEOmatic account (free works), and the connector is separate from any SEOmatic skill you may have installed - the skill needs the connector to reach your data.

URL: https://app.seomatic.ai/api/mcp
Auth: OAuth (the client discovers it automatically)

Fastest path: paste this into your AI assistant and let it do the setup (agents that can run commands or edit config, like Claude Code and Cursor, will install it themselves; chat assistants will give you the exact clicks):

Set up the SEOmatic MCP server for me. Instructions:
https://seomatic.ai/developers/mcp
Server URL: https://app.seomatic.ai/api/mcp (Streamable HTTP, OAuth).
If you can edit MCP config or run commands in this client, do the setup
yourself. Otherwise, give me the exact steps for this client.

Per-client, the exact steps:

Settings -> Connectors -> Add custom connector
Name: SEOmatic
URL:  https://app.seomatic.ai/api/mcp
Then click Connect and approve in the SEOmatic consent screen.

claude mcp add --transport http seomatic https://app.seomatic.ai/api/mcp
# then inside a session: /mcp -> seomatic -> Authenticate

{
  "mcpServers": {
    "seomatic": { "url": "https://app.seomatic.ai/api/mcp" }
  }
}

{
  "mcpServers": {
    "seomatic": {
      "url": "https://app.seomatic.ai/api/mcp",
      "type": "streamableHttp",
      "headers": { "Authorization": "Bearer smk_live_..." }
    }
  }
}
// Agent-guided setup: point the agent at
// https://github.com/Minh42/seomatic-mcp

Settings -> Apps -> Advanced settings -> enable Developer mode
Then: Settings -> Connectors -> Create
Name: SEOmatic
URL:  https://app.seomatic.ai/api/mcp
Auth: OAuth, then approve in the SEOmatic consent screen.
(On Business/Enterprise an admin must allow custom MCP connectors first.)

Discovery follows the MCP spec: the endpoint returns 401 with a WWW-Authenticate pointing at /.well-known/oauth-protected-resource (RFC 9728), whose authorization server metadata lives at /.well-known/oauth-authorization-server (RFC 8414). PKCE (S256) is required; tokens are bound to this resource. Dynamic client registration and client-id metadata documents are both supported.

Connect with an API key (headless)

For headless agents and clients that take a static token, mint a workspace API key and send it as a Bearer token. This is also how the Claude Messages API connector authenticates, via its authorization_token field.

{
  "mcpServers": {
    "seomatic": {
      "url": "https://app.seomatic.ai/api/mcp",
      "headers": { "Authorization": "Bearer smk_live_..." }
    }
  }
}

Try it in 30 seconds (curl)

Two requests prove the whole surface: list the tools your key can call, then call one. Failures come back as isError results with a plain-language reason, never opaque transport errors.

curl -s https://app.seomatic.ai/api/mcp \
  -H "Authorization: Bearer smk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -s https://app.seomatic.ai/api/mcp \
  -H "Authorization: Bearer smk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
    "name":"keyword_research",
    "arguments":{"action":"metrics","keywords":["seo tools"]}}}'

Every successful call returns the payload twice: content (text, for every client) and structuredContent (a JSON object conforming to the declared outputSchema, for clients that want typed data).

Methods

Method	What it does
initialize	Negotiate the protocol version and get serverInfo.
tools/list	The scope-filtered tool roster this key can call.
tools/call	Invoke a tool. Failures return as an isError result, not a transport error, so the agent can react.

What each key can call

The tools/list roster is filtered to the key's scopes, so a client only ever sees tools it can actually call.

Scope	Lane	Tools it unlocks
read:gsc	Free	Direct Search Console reads.
chat:ask	Free	All insight tools: GSC, keywords, backlinks, SERP, analytics, ads, Business Profile, datasets, templates.
agents:act	Paid	The acting tools: SEO tasks, campaigns, bulk edits, blog authoring, skills. Works on any paid plan over MCP.

Acting over MCP works on any paid plan; the same acting tools over the REST API require Infrastructure.

Tool reference (13 consolidated tools)

Over MCP the full surface is grouped into 13 outcome tools, each taking an action that selects the operation. Every tool carries MCP annotations, so a client knows at a glance whether it only reads (readOnlyHint) or can stage a change. Nothing is destructive by default: acting tools stage proposals a human approves in SEOmatic. This reference is generated from the server's real catalog, so it is exactly what tools/list serves. Every tool is already scoped to the connected workspace and its site; the few tools that accept a domain default to your own site when it is omitted, and analyze a competitor when you pass one.

gsc_performanceRead-only

Read Google Search Console performance (clicks, impressions, CTR, position) by query, page, dimension, or period comparison. Your own connected property.

Action	What it does	Parameters
top_queries	top search queries	days, limit
top_pages	top pages	days, limit
dimension_breakdown	by device/country/date	dimension*, days, filterQuery, filterPage, limit
query_page_matrix	cannibalization / query-to-page map	days, maxRows
compare_periods	decay/growth vs the prior period	dimension, days, limit
trend	daily clicks/impressions over time	days

Parameter details

• days (number) Look-back window in days (defaults ~28). 1-90 for most actions; 7-90 for trend.
• limit (number) Row cap. top_queries/top_pages/dimension_breakdown default 50; compare_periods rows per period default 500. Ignored by query_page_matrix (use maxRows) and trend.
• dimension (string) REQUIRED for dimension_breakdown (device|country|date). For compare_periods: query|page (default page). Ignored otherwise. One of: device, country, date, query, page.
• filterQuery (string) dimension_breakdown only: restrict to one exact query.
• filterPage (string) dimension_breakdown only: restrict to one exact page URL.
• maxRows (number) query_page_matrix only: max query-page pairs (default 2000).

gsc_indexingRead-only

Check Google index status and coverage diagnostics for one URL or a batch of URLs (coverage state, crawl status, robots/canonical issues).

Action	What it does	Parameters
inspect	one URL, full diagnostics	url*
batch_inspect	many URLs, summary each	urls*

Parameter details

• url (string) inspect only: the fully-qualified URL to inspect.
• urls (array) batch_inspect only: the URLs to inspect.

keyword_researchRead-only

Research keyword demand: search volume, difficulty, CPC, and intent, plus keyword ideas, Google Trends interest and related queries, and Google Ads keyword performance. Use for what to target and how much demand exists; for who ranks today use serp_competitors.

Action	What it does	Parameters
metrics	volume/difficulty/CPC/intent	keywords*
suggestions	keyword ideas from seeds	keywords*, limit
compare_trends	Trends interest, keywords side by side	keywords*
trend	Trends interest over time for one keyword	keyword*
related	Trends related queries	keyword*
ads_performance	Google Ads keyword performance	days, limit

Parameter details

• keywords (array) metrics/suggestions/compare_trends: the seed or target keywords.
• keyword (string) trend/related: the single keyword to analyze.
• days (number) ads_performance: look-back window in days.
• limit (number) suggestions/ads_performance: max results.

keyword_clustersRead-only

The agent's cached keyword-cluster map built from the workspace's GSC query universe (pillar, cannibalization, gap, and covered clusters).

Action	What it does	Parameters
list		none

backlink_profileRead-only

Read the backlink profile of your own site or any competitor: referring domains, anchor-text distribution, link velocity, and link-prospect intersects. Use for authority and link questions; for rankings use serp_competitors.

Action	What it does	Parameters
summary	totals, referring domains, rank/spam	domain
anchors	anchor-text distribution	domain, limit
velocity	monthly new vs lost referring domains	domain, months
referring_domains	top linking domains	domain, limit
link_prospects	link intersect: linking to competitors but not to us	competitors*, limit

Parameter details

• domain (string) The domain to analyze, e.g. "example.com". Omit it to analyze the connected workspace's own site (the server fills it in); pass it only to analyze a competitor.
• limit (number) anchors (default 25) and referring_domains (default 50).
• months (number) velocity only: months back (default 6).
• competitors (array) link_prospects only: 1-3 competitor domains to intersect against.

serp_competitorsRead-only

Inspect the live search landscape: which SERP features (AI Overview, snippet, PAA, local pack, video) appear for a keyword, plus domain-level top rankings, visibility distribution, and competitor domains. Use for who ranks and why; for keyword demand use keyword_research.

Action	What it does	Parameters
features	which SERP features appear for a keyword	keywords*
domain_rankings	top keywords a domain ranks for	domain, limit
domain_overview	organic visibility distribution	domain
domain_competitors	domains ranking for similar keywords	domain, limit

Parameter details

• keywords (array) features only: the keyword(s) to inspect.
• domain (string) domain_rankings/domain_overview/domain_competitors: the domain. Omit for the connected workspace's own site (the server fills it in); pass only for a competitor.
• limit (number) max results where applicable.

traffic_analyticsRead-only

Google Analytics (GA4) traffic and Google Ads account, campaign, and search-term performance.

Action	What it does	Parameters
overview	GA4 sessions/users/pageviews/bounce	days
sources	GA4 sessions by channel	days
landing_pages	GA4 top entry pages	days, limit
top_pages	GA4 most-viewed pages	days, limit
ads_account	Google Ads account totals	days
ad_campaigns	Google Ads campaign performance	days, limit
ads_search_terms	actual search terms that triggered Ads	days, limit

Parameter details

• days (number) look-back window in days.
• limit (number) max rows where applicable.

local_presenceRead-only

Read the local search presence of the connected business: Business Profile locations, local ranking for money keywords, and review ratings. Available actions depend on what is connected for this workspace. Use for local and map-pack questions; for national rankings use serp_competitors.

Action	What it does	Parameters
list_locations	GBP locations on the account	none
visibility	local organic position for keywords	keywords*
reviews	average rating + review count	location*

Parameter details

• keywords (array) visibility only: the money keywords to measure.
• location (string) reviews only: the Business Profile location id.

site_pagesRead-only

Analyze pages: on-page SEO score and critical issues for a URL, raw crawl metadata (title, meta, headings, links), and the page inventory of the site. Use for page-level diagnosis; for search performance of those pages use gsc_performance.

Action	What it does	Parameters
analyze	SEO score + critical issues	url*
crawl	title/meta/headings/links	url*
inventory	the user's real synced pages	limit

Parameter details

• url (string) analyze/crawl: the URL to inspect.
• limit (integer) inventory only: max pages to return.

dataset_libraryRead-only

The dataset library and page templates that power programmatic pages: list datasets, sample rows, list templates, and read one template.

Action	What it does	Parameters
list_datasets	available datasets	none
dataset_rows	sample rows from one dataset	datasetId*, limit
list_templates	built-in page templates	none
get_template	one template in full	templateId*

Parameter details

• datasetId (string) dataset_rows only: the dataset to sample.
• templateId (string) get_template only: the template to read.
• limit (integer) dataset_rows only: how many rows to sample.

strategy_insightsRead-only

The agent's cached diagnosis for this workspace: a compact snapshot, the current strategy, one raw signal in full, and AI-search content scores.

Action	What it does	Parameters
snapshot	compact brief of cached signals	none
strategy	themes + ranked big plays	none
signal	one cached signal in full	signal*
content_scores	AI-search scores for generated articles	none

Parameter details

• signal (string) signal only: which cached signal to read (e.g. index_coverage, backlink_profile).

task_manageCan stage changes

Read the agent's plan board and stage new SEO task proposals. Proposals NEVER execute: each is an approval-gated card the user reviews.

Action	What it does	Parameters
list	the plan board (filterable)	status, type
get	one task in full detail	taskId*
create stages	stage up to 5 task proposals	tasks*
decide stages	approve or dismiss a staged proposal (the approval loop)	taskId*, decision*

Parameter details

• status (string) list only: filter by task status (proposed, approved,...).
• type (string) list only: filter by task type.
• taskId (string) get/decide: the task to read or decide.
• decision (string) decide only: approve releases the task to the gated pipeline; dismiss archives it. Indexation-destructive types are refused over the API. One of: approve, dismiss.
• tasks (array) create only: up to 5 task objects to stage as proposals (see the SEOmatic docs for the task shape).

campaign_manageCan stage changes

Read campaigns and stage page-scale, content-sweep, or bulk-edit campaigns and blog articles. All staging is proposal-based and approval-gated; nothing publishes without the user.

Action	What it does	Parameters
list	campaigns with status + task counts	status
manage stages	pause/resume/abandon/update a campaign	campaignId*, manageAction*, confirm, brief
propose_page_scale stages	programmatic landing pages at scale	title*, kind*, brief*, rowSourceKind*, rowPrompt, rows, libraryDatasetId, rowTarget, allowGenText, publishAsDraft, pageTemplate
propose_content_sweep stages	N distinct blog articles as a campaign	title*, topics*, brief
propose_bulk_edit stages	one instruction across many pages	taskType*, instruction, title, selectorKind, urls, pathPrefix, segments, maxPages
write_articles stages	direct N-article staging	topics*, autoPublish
save_article stages	save a full article draft (pass title/content/slug) for one-click publish	title*, content*, slug*, excerpt*, metaTitle, metaDescription, featuredImagePrompt*

Parameter details

• status (string) list only: filter campaigns by status. One of: proposed, approved, active, paused, done, abandoned.
• campaignId (string) manage only: the campaign to act on.
• manageAction (string) manage only: what to do to the campaign. One of: pause, resume, abandon, update_brief.
• confirm (boolean) manage + abandon only: must be true to confirm the irreversible action.
• brief (string) manage+update_brief: replacement brief. Also propose_page_scale (template brief) and propose_content_sweep (shared direction).
• title (string) propose_page_scale (required), propose_content_sweep (required), propose_bulk_edit (optional).
• kind (string) propose_page_scale only (required): page kind, e.g. "location pages".
• rowSourceKind (string) propose_page_scale only (required): where page rows come from. One of: ai, user, library, gbp_locations.
• rowPrompt (string) propose_page_scale, rowSourceKind=ai: dataset to generate.
• rows (array) propose_page_scale, rowSourceKind=user: one object per page.
• libraryDatasetId (string) propose_page_scale, rowSourceKind=library: dataset id to attach.
• rowTarget (integer) propose_page_scale only: target number of rows/pages.
• allowGenText (boolean) propose_page_scale only: allow per-row AI text (costs credits).
• publishAsDraft (boolean) propose_page_scale only: publish pages as drafts.
• pageTemplate (string) propose_page_scale only: built-in template id.
• topics (array) propose_content_sweep (required, up to 50) and write_articles (required, 2-50). One distinct article per topic.
• taskType (string) propose_bulk_edit only (required): the sweep type, e.g. ctr_fix, schema, content_refresh.
• instruction (string) propose_bulk_edit only: shared per-page brief.
• selectorKind (string) propose_bulk_edit only: how to select pages. One of: urls, path_prefix, all_pages.
• urls (array) propose_bulk_edit, selectorKind=urls: the pages.
• pathPrefix (string) propose_bulk_edit, selectorKind=path_prefix: the prefix.
• segments (array) propose_bulk_edit: advanced mixed-template selectors (overrides selectorKind/instruction).
• maxPages (integer) propose_bulk_edit only: cap the sweep size.
• autoPublish (boolean) write_articles only: default false (stage as drafts).
• content (string) save_article only (required): full Markdown body.
• slug (string) save_article only (required): the URL slug.
• excerpt (string) save_article only (required): the excerpt.
• metaTitle (string) save_article only: meta title.
• metaDescription (string) save_article only: meta description.
• featuredImagePrompt (string) save_article only (required): image prompt.

* = required for that action. The complete fine-grained tool list behind these, with each input schema, is in the REST reference.

Free tier limits

A free workspace's tool calls draw from the same monthly question quota as ChatSEO, shared across chat, MCP, the REST tool bridge, and the CLI, so there is one meter everywhere. initialize and tools/list are always free; only tools/call consumes a question. Your first connect banks 10 bonus questions on top of the monthly allowance, enough for a full first audit. When the quota is exhausted the call returns an isError result carrying a one-click upgrade link, plus a referral link that banks extra free questions for both sides. Paid workspaces are not question-metered.

Independent of plan, each key is rate-limited to 60 tool calls per minute and 1,000 per hour, enough for any real session and a backstop against runaway loops. To revoke access: remove the connector in your assistant, or revoke the key or OAuth grant in SEOmatic Settings. Either kills the connection immediately.

Troubleshooting

• The model asks for your domain. It never needs one: every tool is scoped to the connected workspace. Tell it to call the tool directly. Tools that accept a domain default to your own site when it is omitted.
• No acting tools in tools/list. Expected on a free workspace or a key without agents:act: the roster only shows what the key can call. Acting tools appear on any paid plan.
• Acting tools missing on a paid plan. The SEO agent may be turned off for the workspace, or the connection an action needs (for example your CMS) is not set up. Check Settings in SEOmatic, then reconnect.
• Wrong workspace connected. The OAuth grant is scoped to the one workspace you picked at consent. Remove the connector and reconnect, choosing the right workspace.
• Want a guided audit? Install the free seomatic-seo-audit skill alongside the connector: it walks your assistant through a full, methodical audit of your site instead of ad-hoc questions.
• Tool failures. Failures come back as isError results with a plain-language reason the model can act on, never as opaque transport errors.

Each local area page used to take us half a day to create and optimize.

With SEOmatic, we can create hundreds of pages in the same time, which helps our clients make the best use of their budget.

It's transformed how we deliver scalable SEO solutions.

Will Hawkins

Marketing Director, Digi-Business UK

Give Your Site an SEO Team

Agents read your Search Console data, do the work, and prove what actually moved. You decide what ships.

14-Day Free Trial. $1 card check, refunded. Cancel Anytime.