# MCP Tool Reference

Source: https://www.ranked.ai/developers/mcp/tools

> 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.

> **Info:** Managed-service projects (Ranked AI does the work, from $99/month with a free trial, software suite included) cannot be created here. They start from the dashboard's Add Project flow. The AI should confirm the website URL with you before calling this tool.

### 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.

> **Warning:** This permanently deletes the keywords and their position history.

### 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

> **Info:** This and the other content tools (`ranked_approve_content`, `ranked_request_revision`, `ranked_update_content_preferences`, `ranked_update_publishing_preferences`) only act on **managed** projects. On a self-serve software project they return an explanation of the managed-service upgrade (with the project's `addServiceUrl`) instead of "no content found".

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 |