Lists the keywords of a rank tracking project in alphabetical order, paginated by cursor (limit up to 200): text, status (active = measured on every check; inactive = paused, history kept), labels (label_ids and labels with their name and color), the engines and countries each one is measured on (measured_on, as {engine}_{country} keys), search volume, CPC and competition when fetched, and the latest position per engine, country and device (latest_positions: position, previous position, change, ranking URL, SERP features, checked_at). latest_positions is sorted by engine, then country, then device (alphabetically), not in the order they were collected; checked_at is the time of the collection pass that measured it, and a pass stamps one time for everything it measures, so the countries of one pass share the same checked_at (ties are normal: they do not say which country came first). latest_positions lists what the project measures today, each entry with measured: a leftover of a combination no longer measured may come with measured: false (the cleanup removes it): skip it, it is never a position of today. For a keyword's position "today", use the project's main engine, country and device (check_summary.pos_key in seo_rankings.projects.get) or each entry of combo_summaries, among those in measured_on; never compare two different combinations. A position past 30 (an imported one) shows as null, like every position outside the top 30. Filters: status (active by default, inactive or all), label_id, engine_key. Filters run on the page read, so a page can bring fewer than limit while has_more is true: follow next_cursor.
Alcance
seo_rankings:read
Permiso
Ver el módulo
Tool del MCP
seo_rankings_keywords_listEn la superficie completa; en la compacta, mb_execute_operation con id: "seo_rankings.keywords.list".
Costo declarado: hasta 203 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).
Parámetros
project_idstringrutarequerido
Rank project id (from seo_rankings.projects.list).
limitintegerqueryopcional
How many items this page brings at most (see the maximum and the default in the schema).
Por defecto: 50
cursorstringqueryopcional
The next_cursor of the previous page, exactly as it came (only for the same list and filters); without it, the first page.
statusenumqueryopcional
active (default: measured on every check), inactive (paused, history kept) or all.
Valores: active, inactive, all · Por defecto: "active"
label_idstringqueryopcional
Only keywords with this label.
engine_keystringqueryopcional
Only keywords measured on this engine and country (google_AR).
Lists the active keywords of a rank tracking project whose latest position is between min_position and max_position (default 4 to 20: where climbing a few places changes the traffic), sorted by search volume, highest first (keywords without volume last), then by position. It measures on the project's main engine, country and device (the same as its position summary) unless position_key says another ({engine}_{country}_{device}, one of measured_pos_keys in seo_rankings.projects.get: 400 rank_position_key_not_measured otherwise), and it counts only the active keywords measured on that country. Each keyword has keyword_id, keyword, position, previous_position (the check before; null if it was not ranked), url (the ranking page) and search_volume. data brings up to limit keywords (20 by default, up to 100); active_keywords and in_zone say how many there are in total. The distribution, average position and the biggest gains and losses are in seo_rankings.projects.get (check_summary). It reads the project's keywords, up to 1000: with more, truncated is true. Not found if the project is not of this organization.
Alcance
seo_rankings:read
Permiso
Ver el módulo
Tool del MCP
seo_rankings_keywords_opportunitiesEn la superficie completa; en la compacta, mb_execute_operation con id: "seo_rankings.keywords.opportunities".
Costo declarado: hasta 1002 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).
Parámetros
project_idstringrutarequerido
Rank project id (from seo_rankings.projects.list).
min_positionintegerqueryopcional
Lowest position of the zone, inclusive (default 4). Positions past 30 are not measured.
Por defecto: 4
max_positionintegerqueryopcional
Highest position of the zone, inclusive (default 20; more than 30 brings nothing more: MB Suite measures the top 30).
Por defecto: 20
position_keystringqueryopcional
Engine, country and device, {engine}_{country}_{device}: one of the project's measured_pos_keys (seo_rankings.projects.get); another one is 400 rank_position_key_not_measured. Default: the project's main one (the pos_key of check_summary).
limitintegerqueryopcional
How many keywords of the zone to return, by search volume (default 20, up to 100); in_zone says how many there are.
Por defecto: 20
Respuesta
position_keystring | null
Engine, country and device measured; null when no keyword has a position yet.
min_positionnumber
max_positionnumber
active_keywordsinteger
Active keywords measured on that engine and country (the ones searched for the zone); with position_key null, every active keyword read.
in_zoneinteger
How many of them are between min_position and max_position (data brings up to limit).
dataarray<object>
The keywords of the zone, the highest search volume first.
truncatedboolean
true = the project has more than 1,000 keywords and only the first 1,000 were read.
Returns one tracked keyword with its status, labels (with their names), the engines and countries it is measured on (measured_on), search volume data and its latest position per engine, country and device (latest_positions, sorted by engine, then country, then device, not in collection order). checked_at is the time of the collection pass that measured each one; a pass stamps one time for everything it measures, so countries measured in the same pass share it (ties are normal). latest_positions lists what the project measures today, each entry with measured: a leftover may come with measured: false (the cleanup removes it): skip it. For its position "today", use the project's main engine, country and device (check_summary.pos_key in seo_rankings.projects.get) or each entry of combo_summaries, among those in measured_on; never compare two different combinations. Use seo_rankings.history.get for its full position history. Not found if the id is not a keyword of this organization.
Alcance
seo_rankings:read
Permiso
Ver el módulo
Tool del MCP
seo_rankings_keywords_getEn la superficie completa; en la compacta, mb_execute_operation con id: "seo_rankings.keywords.get".
Costo declarado: hasta 2 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).
Parámetros
keyword_idstringrutarequerido
Keyword id (from seo_rankings.keywords.list).
Respuesta
idstring
project_idstring
keywordstring
statusenum
active (measured on every check) or inactive (paused, history kept).
Valores: active, inactive
status_changed_atnumber | null
inactive_periodsarray<object>
Periods the keyword was paused (to: null = still paused).
label_idsarray<string>
Label ids (seo_rankings.labels.list); their names are in labels.
labelsarray<object>
The keyword's labels with their name and color, in the order of label_ids (labels that no longer exist are left out).
engine_keysarray<string> | null
Engine and country keys the keyword was assigned to; null = every engine of the project.
measured_onarray<string>
Engine and country keys it is really measured on ({engine}_{country}).
search_volumenumber | null
Monthly search volume (DataForSEO), when fetched.
cpcnumber | null
Cost per click (USD) from Google Ads data, when fetched.
competitionstring | null
Google Ads competition as DataForSEO returned it, kept as text: a level (LOW, MEDIUM, HIGH) or, in volumes fetched long ago, a 0–1 number written as text ("0.54"). To compare keywords use competition_index.
competition_indexnumber | null
Competition index 0 to 100, when fetched.
monthly_searchesarray<object>
Search volume of the last 12 months, when fetched.
latest_positionsarray<object>
Latest position per engine, country and device, sorted by engine, country and device: what the project measures today for the keyword (measured true); a leftover of a combination no longer measured may come with measured false (the cleanup removes it): skip it, it is never a position of today.
Adds up to 100 keywords to a rank tracking project. Texts are trimmed, lowercased and de-duplicated; a keyword that is already active, or repeated in the same request, is skipped and counted in duplicates_skipped; one that exists as inactive is reactivated with its history (reactivated; with engine_keys, its latest position on a country it is no longer measured on is cleared). When every text given is already active, nothing is written and it is 409 rank_keywords_already_exist (details.duplicates), so a script that runs twice can treat that code as done. New keywords are active and measured from the next check; the plan's quota of active keywords per project (and per engine and country, when the plan has one) applies: 409 limit_reached (details.resource rank_keywords / rank_engine_keywords) when the add would exceed it. Optional labels (unknown ids are ignored and returned) and, in projects with 2+ engines, the engine keys ({engine}_{country}) to measure the new keywords on (default: all). With fetch_search_volume: true the monthly search volume, CPC and competition of the NEW keywords are fetched from DataForSEO after the response (paid; never in demo organizations); the default is false (nothing is paid unless asked; the app's dialog asks for it). Outside the app, with fetch_search_volume: true it needs a dry run and its confirm_token; without it, it runs directly. Nothing is measured until a check runs.
Instrucciones para agentes
Mention how many were added, reactivated or skipped as duplicates. Positions appear after the next scheduled check (or seo_rankings.checks.trigger).
Pide confirmación: primero dry_run: true (vista previa y confirm_token, que vale 10 minutos y una sola vez), después el mismo cuerpo con confirm_token. En unas pocas, solo con ciertos datos: la descripción dice cuándo. Por qué y cómo: Vista previa y confirmación. En esta, solo cuando: fetch_search_volume is true (the search volume of the new keywords is fetched from DataForSEO, which is paid).
Alcance
seo_rankings:write
Permiso
Editar en el módulo
Tool del MCP
seo_rankings_keywords_addEn la superficie completa; en la compacta, mb_execute_operation con id: "seo_rankings.keywords.add".
Costo declarado: hasta 400 lecturas y 101 escrituras por llamada (cuentan en el cupo diario). Toca una plataforma externa (dataforseo): cuenta en el cupo de operaciones externas.
Parámetros
project_idstringrutarequerido
Rank project id (from seo_rankings.projects.list).
keywordsarray<string>cuerporequerido
Keywords to track (up to 100 per call). They are trimmed, lowercased and de-duplicated.
label_idsarray<string>cuerpoopcional
Labels for the new keywords (ids that do not exist are ignored).
engine_keysarray<string>cuerpoopcional
Projects with 2+ engines: the engine and country keys (google_AR) to measure the new keywords on. Omitted: every engine of the project.
fetch_search_volumebooleancuerpoopcional
true also fetches the monthly search volume, CPC and competition of the NEW keywords from DataForSEO after the response (paid, one external call per 700 keywords). Default false: nothing is paid unless you ask (the app's add dialog sends true).
Por defecto: false
Respuesta
addednumber
New keywords created.
reactivatednumber
Inactive keywords with the same text that were reactivated (history kept).
duplicates_skippednumber
Texts skipped: already active in the project, or repeated in the same request.
keywordsarray<object>
The keywords added or reactivated.
ignored_label_idsarray<string>
Label ids sent that do not exist in the organization (ignored).
search_volume_requestedboolean
true when the search volume of the new keywords was requested from DataForSEO (paid).
Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.En la práctica esta operación se simula: no sale nada y la respuesta trae simulated: true.
Deletes one tracked keyword together with its whole position history. The keyword goes to the 30-day trash with its 150 most recent measurements (older ones are deleted for good); an owner or admin can restore it (platform.trash.restore: back in its project, with the project's counters recomputed; 409 if the project no longer exists, if an active keyword with the same text exists, or if the active-keyword quota is full). To stop measuring a keyword WITHOUT losing anything, deactivate it with seo_rankings.keywords.bulk.set_status instead. The project's counters and position summary are recomputed. Outside the app it needs a dry run and a confirm_token, except a REST DELETE with a key allowed to delete.
Con una API key, este DELETE se ejecuta directo: el registro queda 30 días en la papelera y la respuesta trae su trash_item_id. Con un token OAuth, y por el MCP, pide dry_run → confirm_token.
Alcance
seo_rankings:writey «Permitir eliminar» (seo_rankings:delete en OAuth)
Permiso
Editar en el módulo
Tool del MCP
seo_rankings_keywords_deleteEn la superficie completa; en la compacta, mb_execute_operation con id: "seo_rankings.keywords.delete".
Deletes up to 500 keywords of a project with their position history, like the selection bar of the app. Each keyword goes to the 30-day trash with its 150 most recent measurements and can be restored on its own. Ids that are not keywords of this project are skipped and returned in not_found. The project's counters and position summary are recomputed. Prefer deactivating (seo_rankings.keywords.bulk.set_status) when the history matters. Outside the app it requires a dry run (which counts the measurements that will be lost) and a confirm_token.
Pide confirmación: primero dry_run: true (vista previa y confirm_token, que vale 10 minutos y una sola vez), después el mismo cuerpo con confirm_token. En unas pocas, solo con ciertos datos: la descripción dice cuándo. Por qué y cómo: Vista previa y confirmación.
Alcance
seo_rankings:writey «Permitir eliminar» (seo_rankings:delete en OAuth)
Permiso
Editar en el módulo
Tool del MCP
seo_rankings_keywords_bulk_deleteEn la superficie completa; en la compacta, mb_execute_operation con id: "seo_rankings.keywords.bulk.delete".
EscrituraMasiva · hasta 500IdempotenteDesde 2026-11-01
Activates or deactivates up to 500 keywords of a project. inactive pauses them: no measurement (no cost, no quota) while the document, labels, last position and whole history are kept; active measures them again from the next check and counts against the plan's quota of active keywords (409 limit_reached, resource rank_keywords, if it would be exceeded). Idempotent: only the keywords whose status actually changes are written (changed). Ids not in the project come back in not_found. The project's counters and position summary are recomputed. Outside the app it requires a dry run and a confirm_token.
Pide confirmación: primero dry_run: true (vista previa y confirm_token, que vale 10 minutos y una sola vez), después el mismo cuerpo con confirm_token. En unas pocas, solo con ciertos datos: la descripción dice cuándo. Por qué y cómo: Vista previa y confirmación.
Alcance
seo_rankings:write
Permiso
Editar en el módulo
Tool del MCP
seo_rankings_keywords_bulk_set_statusEn la superficie completa; en la compacta, mb_execute_operation con id: "seo_rankings.keywords.bulk.set_status".
EscrituraMasiva · hasta 500IdempotenteDesde 2026-11-01
Sets the engine and country combinations ({engine}_{country}, from the project's engines) that up to 500 keywords are measured on; the same set for all of them, replacing what they had. Only meaningful in projects with 2+ engines (with one engine nothing is assigned: updated 0). Keys the project does not measure are ignored; at least one valid key is required (400 rank_engine_keys_required). The plan's quota of active keywords per engine and country applies (409 limit_reached, resource rank_engine_keywords). A country taken away from a keyword clears that keyword's latest position there (its history stays), and one it is measured on again starts without the old one; the dry run counts them in positions_cleared and warns about it. The project's position summaries are recomputed. Outside the app it requires a dry run and a confirm_token.
Pide confirmación: primero dry_run: true (vista previa y confirm_token, que vale 10 minutos y una sola vez), después el mismo cuerpo con confirm_token. En unas pocas, solo con ciertos datos: la descripción dice cuándo. Por qué y cómo: Vista previa y confirmación.
Alcance
seo_rankings:write
Permiso
Editar en el módulo
Tool del MCP
seo_rankings_keywords_bulk_set_enginesEn la superficie completa; en la compacta, mb_execute_operation con id: "seo_rankings.keywords.bulk.set_engines".
Costo declarado: hasta 302 lecturas y 501 escrituras por llamada (cuentan en el cupo diario).
Parámetros
project_idstringrutarequerido
Rank project id (from seo_rankings.projects.list).
keyword_idsarray<string>cuerporequerido
Keyword ids of the project (from seo_rankings.keywords.list), up to 500; ids that are not in the project are skipped and returned in not_found.
engine_keysarray<string>cuerporequerido
Engine and country keys (google_AR) to measure the keywords on; keys the project does not measure are ignored.
EscrituraMasiva · hasta 500IdempotenteDesde 2026-11-01
Replaces the labels of up to 500 keywords with label_ids (the full set for each one; [] removes them all). Labels are the organization's keyword labels (seo_rankings.labels.list); ids that do not exist are ignored and returned in ignored_label_ids. Only keywords that exist in this organization are written (and only those of project_id when it is given); the rest come back in not_found. Outside the app it requires a dry run and a confirm_token.
Pide confirmación: primero dry_run: true (vista previa y confirm_token, que vale 10 minutos y una sola vez), después el mismo cuerpo con confirm_token. En unas pocas, solo con ciertos datos: la descripción dice cuándo. Por qué y cómo: Vista previa y confirmación.
Alcance
seo_rankings:write
Permiso
Editar en el módulo
Tool del MCP
seo_rankings_keywords_bulk_set_labelsEn la superficie completa; en la compacta, mb_execute_operation con id: "seo_rankings.keywords.bulk.set_labels".
Costo declarado: hasta 550 lecturas y 500 escrituras por llamada (cuentan en el cupo diario).
Parámetros
keyword_idsarray<string>cuerporequerido
Keyword ids (from seo_rankings.keywords.list), up to 500; ids that do not exist (or are of another project, when project_id is given) are returned in not_found.
label_idsarray<string>cuerporequerido
The full set of labels for each keyword (replaces the current ones; [] removes them all).
project_idstringcuerpoopcional
When given, keywords of other projects are skipped (returned in notFound).
Imports historical positions (for example from another rank tracker's CSV) into a project: up to 500 keywords, each with up to 104 measurements (date in ms + organic position, null when the domain was not in the results; MB Suite measures the top 30, so a position past 30 is stored as null, like the app's CSV import, and counted in positions_outside_top30), for ONE engine, country (must be one of the project's engines: 400 rank_import_engine_not_in_project) and device (must be one of the project's devices: 400 rank_import_device_not_in_project). New keywords are created active (with the engine keys given or the import's engine and country), inactive ones are reactivated, and the plan's quota of active keywords applies. One measurement per keyword and day: a day that already has one (or repeats in the payload) is skipped (duplicates_skipped). Each keyword's latest position is updated only when the import is newer and the keyword is measured on that engine, country and device; the summaries are recomputed, and only the imported combination's previous summary rotates (when the import is newer than its current one). dry_run returns the plan (new, reactivated, measurements, duplicates) without writing. With fetch_search_volume: true the search volume of the NEW keywords is fetched from DataForSEO after the response (paid; never in demo organizations); the default is false. Outside the app, with fetch_search_volume: true running it needs the confirm_token of its dry run; without it, the dry run is optional.
Pide confirmación: primero dry_run: true (vista previa y confirm_token, que vale 10 minutos y una sola vez), después el mismo cuerpo con confirm_token. En unas pocas, solo con ciertos datos: la descripción dice cuándo. Por qué y cómo: Vista previa y confirmación. En esta, solo cuando: fetch_search_volume is true (the search volume of the new keywords is fetched from DataForSEO, which is paid).
Alcance
seo_rankings:write
Permiso
Editar en el módulo
Tool del MCP
seo_rankings_keywords_importEn la superficie completa; en la compacta, mb_execute_operation con id: "seo_rankings.keywords.import".
Costo declarado: hasta 10000 lecturas y 55000 escrituras por llamada (cuentan en el cupo diario). Toca una plataforma externa (dataforseo): cuenta en el cupo de operaciones externas.
Parámetros
project_idstringrutarequerido
Rank project id (from seo_rankings.projects.list).
engineenumcuerporequerido
Search engine: google or bing.
Valores: google, bing
country_codestringcuerporequerido
Country of the imported history; the engine and country must be one of the project's engines.
deviceenumcuerporequerido
Device of the imported history: desktop or mobile, and one of the project's devices (devices of seo_rankings.projects.get); another one is 400 rank_import_device_not_in_project.
Valores: desktop, mobile
keywordsarray<object>cuerporequerido
The keywords with their measurements, up to 500.
location_namestringcuerpoopcional
Default: the project's location for that engine and country.
language_codestringcuerpoopcional
Default: the project's language for that engine and country.
fetch_search_volumebooleancuerpoopcional
true also fetches search volume, CPC and competition for the NEW keywords from DataForSEO after the import (paid). Default false (the app's import sends true).
Por defecto: false
Respuesta
keywords_addednumber
keywords_reactivatednumber
checks_creatednumber
Measurements written.
duplicates_skippednumber
Measurements skipped because that keyword already had one that day (or it repeated in the payload).
positions_outside_top30number
Positions past 30 that were stored as null (not in the top 30).
search_volume_requestedboolean
true when the search volume of the new keywords was requested from DataForSEO (paid).
Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.En la práctica esta operación se simula: no sale nada y la respuesta trae simulated: true.
