MCP Tool Reference

Detailed reference for all MCP tools

Read tools

ranked_get_project_overview

List all your projects, or get detailed metrics for one project. Call this first — every other tool needs a project_id from it.

Parameters

Parameter	Type	Required	Description
`project_id`	string	No	Project UUID. Omit to list all accessible projects

Response includes

Without project_id: every accessible project with keyword, AI prompt, and audit issue counts, plus each project's productMode (managed or software). When the account has software projects the list also carries softwarePlan (capacity, usage, price, renewal) and a productModes explainer.
With project_id: average position, AI visibility, audit issue counts by severity, backlink totals, and content calendar counts. Software projects add an addServiceUrl, the link that upgrades the project to the managed service.

ranked_get_keyword_rankings

Get keyword positions across all search channels with position changes.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`limit`	number	No	Max keywords to return (default: 50, max: 1000)
`date_range`	string	No	Comparison period: `7d`, `30d`, `60d`, `90d`, `180d`, `365d`, `all` (default: `30d`)

Response fields

Each keyword includes:

Field	Description
`desktopPosition`	Current Google Desktop rank
`mobilePosition`	Current Google Mobile rank
`aiModePosition`	Current Google AI Mode rank
`mapsPosition`	Current Google Maps rank
`desktopChange`	Position change for the date range
`mobileChange`	Position change for the date range
`aiModeChange`	Position change for the date range
`mapsChange`	Position change for the date range
`netChange`	Sum of all channel changes (positive = improved)
`location`	Target location name

Net change

A positive netChange means the keyword improved. It is the sum of position changes across all four channels for the selected date range.

ranked_get_ai_visibility

Get brand visibility across 6 AI models.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`limit`	number	No	Max prompts to return (default: 20, max: 200)

Response includes

Overall visibility percentage and average position
Per-prompt breakdown with visibility change indicators
Per-model mention rates and average positions
AI search volume estimates per prompt
Per-model status (mentioned, position, citation count) from latest analysis

ranked_get_audit_summary

Get the latest audit results scoped to the most recent audit task.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`limit`	number	No	Max issues to return (default: 20, max: 50)
`severity`	string	No	Filter: `critical`, `warning`, or `notice`

ranked_get_audit_details

Get the affected URLs for a specific audit issue. Use ranked_get_audit_summary first to get issue IDs.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`issue_id`	string	Yes	Audit issue UUID from `ranked_get_audit_summary`
`limit`	number	No	Max affected items to return (default: 20, max: 50)

ranked_get_backlink_summary

Get backlink profile overview.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`limit`	number	No	Max referring domains (default: 20, max: 50)

Response includes

Total backlinks and referring domains
DoFollow/NoFollow breakdown
New and lost backlinks in last 30 days
Top referring domains

ranked_get_content_calendar

Get content calendar items.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`limit`	number	No	Max items (default: 30, max: 50)
`status`	string	No	Filter by status name (e.g., `Approved`, `Published`)

ranked_get_heatmaps

Get local SEO heatmaps showing how the business ranks across a geographic grid in Google Maps.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`limit`	number	No	Max heatmaps to return (default: 10, max: 20)
`heatmap_type`	string	No	Filter: `competition` or `ranking`

ranked_get_sitemap_indexing

Get sitemap URLs and their Google indexing status.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`limit`	number	No	Max URLs to return (default: 50, max: 100)
`indexed_status`	string	No	Filter: `submitted`, `indexed`, or `not_indexed`

ranked_get_search_console_metrics

Get Google Search Console traffic data. Requires the project to have Google Search Console connected. GSC keeps around 16 months of history, and the most recent 2-3 days can be partial while Google finalizes them.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`days`	number	No	Trailing window in days (default: 30, max: 500). Ignored when `start_date` is set
`start_date`	string	No	`YYYY-MM-DD` exact window start, overrides `days`
`end_date`	string	No	`YYYY-MM-DD` exact window end (default: today)
`limit`	number	No	Max top queries to return (default: 15, max: 100)

Response includes

Total impressions and clicks for the window (computed from daily property totals)
Average CTR and average position
Top queries with per-query impressions, clicks, CTR, and position
Daily impressions/clicks breakdown

For period comparisons ("this month vs last month"), call the tool twice with two exact windows and compare the results.

ranked_get_analytics_metrics

Get Google Analytics traffic data. Requires the project to have Google Analytics connected. GA aggregates in the property's timezone, so today and yesterday can be partial.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`days`	number	No	Trailing window in days (default: 30, max: 500). Ignored when `start_date` is set
`start_date`	string	No	`YYYY-MM-DD` exact window start, overrides `days`
`end_date`	string	No	`YYYY-MM-DD` exact window end (default: today)

Response includes

Sessions, users, page views, and bounce rate for the window
Daily sessions/users breakdown
Channel breakdown (organic, direct, referral, ...) with sessions, users, and new users

Write tools

ranked_create_software_project

Create a self-serve SEO Software project for the connected account from a website URL. No plan or payment is needed to create it: the project exists immediately and appears in the dashboard's Software Suite. Software projects are run by the account itself (rank tracking, AI visibility prompts, audits, backlinks, heatmaps, integrations, reports); Ranked AI's team does no content, publishing or optimization work on them. Adding keywords or prompts and running scans needs the account's SEO Software plan ($4.99/month per 100 tracked keywords and per 100 AI prompts, one plan for all software projects) and the response says whether one is active and where to add it.

Parameters

Parameter	Type	Required	Description
`website_url`	string	Yes	The website to track, e.g. `acme.com` or `https://acme.com`
`name`	string	No	Project name; defaults to the domain

Response includes

The new project's id, name and dashboard link
Whether the account's software plan is active, its remaining capacity, and the page to add or change the plan
An addServiceUrl that opens the "Add our SEO service" plan picker on the project

ranked_add_keywords

Add keywords to track in Google search results. Duplicates are automatically skipped.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`keywords`	string[]	Yes	Keyword strings to track
`location`	string	No	Target location, e.g. `Waterbury, Connecticut, United States` (default: `United States`)

ranked_remove_keywords

Remove tracked keywords by ID. Use ranked_get_keyword_rankings first to get keyword IDs.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`keyword_ids`	string[]	Yes	Keyword UUIDs to remove

ranked_add_prompts

Add prompts to track brand visibility across 6 AI models. Prompts should be natural questions someone would ask an AI assistant, without mentioning the brand name.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`prompts`	string[]	Yes	Prompt questions to track
`target_location`	string	No	Target location (default: `Global`)

ranked_request_topic

Submit a topic request for content generation. The topic is queued for article creation.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`topic`	string	Yes	The topic or article title to request
`description`	string	No	Optional context or brief for the content

ranked_approve_content

Approve a content item for publishing. Sets the status to Approved and adds it to the publishing queue. Use ranked_get_content_calendar first to get content IDs.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`content_id`	string	Yes	Content calendar item UUID

ranked_request_revision

Request a revision on a content item. Sets the status to Revising and attaches the revision notes.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`content_id`	string	Yes	Content calendar item UUID
`notes`	string	Yes	What needs to be changed

ranked_generate_report

Generate a shareable SEO report link covering keywords, AI visibility, audits, backlinks, and analytics.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`date_range`	string	No	`7days`, `30days`, `90days`, or `lastMonth`
`title`	string	No	Custom report title

ranked_run_audit

Start a technical SEO audit that crawls the project website for issues. Results are available via ranked_get_audit_summary once the crawl completes.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`max_pages`	number	No	Maximum pages to crawl (default: 100, max: 500)

ranked_update_content_preferences

Update the project's content preferences (tone, style, topics, guidelines). This overwrites the existing content preferences text.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`preferences`	string	Yes	The new content preferences text

ranked_update_publishing_preferences

Update the project's publishing preferences (schedule, formatting, SEO guidelines). This overwrites the existing publishing preferences text.

Parameters

Parameter	Type	Required	Description
`project_id`	string	Yes	Project UUID
`publishing_preferences`	string	Yes	The new publishing preferences text

This page is also available as markdown for AI agents, and the whole reference as an OpenAPI spec. Questions? Developer support.