Outrank Cli MCP Server

Outrank CLI

Agent-first CLI for the Outrank agent API, with a built-in MCP server for Claude Code, Cursor and other MCP clients.

Install

Requires Node.js 18+. Works on macOS, Linux, and Windows.

npm install -g outrank-cli
outrank-cli --help

Get an API key

1. Sign in to your Outrank account at https://www.outrank.so.
2. Open Settings → API keys: https://www.outrank.so/dashboard/settings/api-keys.
3. Click Create key, give it a name, and copy the outr_live_... value. The key is shown only once — store it somewhere safe.
4. Revoke a key from the same page if it ever leaks. Generate a fresh one and re-run auth login.

You can also rotate keys at any time; each key is independent and can be revoked without affecting the others.

Current scope

This repo currently targets the agent endpoints that already exist in outrank:

• mcp (the stdio MCP server that exposes the commands below as tools, see MCP server)
• auth login|whoami|status|profiles|logout
• products list|get|create|update|pause|resume
• products integrations providers|prepare|connect|poll|validate|list|create|get|update|test|delete
• products integrations notion databases|schema
• products integrations framer collections|fields
• products integrations webflow sites|collections|fields|items
• products output-settings get|update for product article settings
• products target-audiences list|replace
• products competitors list|replace
• products gsc status|connect|poll|reconnect|disconnect|accounts|properties|set-property|performance|search-analytics|inspect-url|cannibalization
• products linking sources get|update
• products linking detect
• products linking target-config get|update
• products linking targets list|add-manual|upsert|clear-customizations|delete
• products backlinks get|update|credits|earned|unverified|check-removal|reverify|subscription|subscribe-quote
• keywords list|get|export|generation-status|add|update|suggest|generate|bulk-reschedule|delete|bulk-delete
• articles list|create|get|get-content|update|update-content|replace|bulk-replace|upload-image|upload-featured-image|publish|sync|retry-publish|delete|precreate|generate
• products blog ... for a hosted Outrank Blog: posts list|create|get|update|delete|get-content|update-content|publish|unpublish|sync, design get|patch|update|publish|discard, settings, pages, categories, authors, domain, redirects, snippets, subscribers, webhooks, preview and analytics
• improvements settings get|update
• improvements analyze
• improvements candidates list|brief|edit-brief|schedule
• improvements tasks list|reschedule|cancel|edit-brief|execute
• improvements executions list|get|decisions|push
• marketplace seller status|onboard|eligibility|settings|integrations|stripe|complete-onboarding|placements|earnings|content-history
• marketplace notifications list|mark-read
• marketplace buyer status|billing-status|subscription|subscribe-quote|checkout|change-plan|target-pages|participation|placements|article|credits
• ai-cited-lists status|overview|lists|outreach|offers|wins|questions|settings|mailbox|top-up-consent|entry|setup|citations for AI-Cited Lists (Backlinks Enterprise)
• subscription status
• usage stats
• billing portal-url
• billing purchase-products quote|buy

The broader roadmap from the internal implementation plan is larger than the live backend surface. This CLI is structured so new groups can be added cleanly as the server catches up.

Auth

The CLI reads credentials in this order of precedence:

1. --api-key <key> and --base-url <url> on the command line (highest priority, per-call)
2. A profile selected with --profile <name> or OUTRANK_PROFILE. A selected profile is used as-is: OUTRANK_API_KEY and OUTRANK_BASE_URL are ignored, and a profile without a stored key fails with CLI_AUTH_REQUIRED instead of silently using another key
3. OUTRANK_API_KEY and OUTRANK_BASE_URL environment variables
4. The default profile in ~/.outrank/config.json, populated by outrank-cli auth login <api-key> (lowest priority, persistent)

auth status shows which profile is active and where its key and base URL came from (flag, env, profile, or profile (env ignored) when an environment variable was set but a higher-priority source won).

Pick one. For interactive use on your own machine, auth login is simplest. For CI / ephemeral environments, prefer the env var.

# Sign in through the browser, so no key is ever pasted (also what an AI assistant should use)
outrank-cli auth login --browser

# Or store an API key once
outrank-cli auth login outr_live_xxx
outrank-cli auth status     # confirms the key is stored
outrank-cli auth whoami     # round-trips it against the server

# OR per-shell env var (no config file written)
export OUTRANK_API_KEY="outr_live_xxx"   # macOS / Linux (bash, zsh)
outrank-cli auth whoami

# OR per-call (useful in scripts)
outrank-cli auth whoami --api-key outr_live_xxx

On Windows PowerShell, set the env var with $env:OUTRANK_API_KEY = "outr_live_xxx". On Windows cmd.exe, use set OUTRANK_API_KEY=outr_live_xxx.

Sign out / rotate:

outrank-cli auth logout     # clears apiKey from the default profile in ~/.outrank/config.json

Profiles (one per organization)

API keys are scoped to one organization. Store one profile per organization and switch with --profile:

outrank-cli auth login outr_live_xxx --profile acme               # the first stored key becomes the default profile
outrank-cli auth login outr_live_yyy --profile globex             # a second profile; the default does not change
outrank-cli auth login outr_live_yyy --profile globex --default   # ...unless you ask for it
outrank-cli auth profiles                                         # lists profiles with redacted keys, marks the default
outrank-cli products list --profile globex                        # per call
export OUTRANK_PROFILE=globex                                     # per shell
outrank-cli auth logout --profile globex                          # clears only that profile's key

auth login and auth logout without --profile act on the default profile. auth login verifies against and stores the base URL it resolves with the same precedence as every other command: --base-url, else OUTRANK_BASE_URL (ignored when a profile is selected), else the profile's stored value, else the default. Re-running auth login for a stored profile therefore keeps that profile's base URL. The config file keeps the default profile mirrored in the top-level apiKey / baseUrl keys, so an older outrank-cli (0.5.x) on the same machine keeps working; it only ever sees the default profile. A config file that cannot be parsed, or that contains a profile name the CLI does not accept, fails every command with CLI_CONFIG_UNREADABLE (the path is in error.details.config_path), and auth login / auth logout never overwrite it. A failed save is CLI_CONFIG_UNWRITABLE and nothing is stored. auth status and auth profiles still work when the selected profile does not exist, so you can always inspect what is stored.

MCP server

outrank-cli mcp starts a Model Context Protocol server on stdio, so Claude Code, Cursor and other MCP clients can call Outrank directly. The server runs on the same command layer as the CLI: every command except auth login, auth logout and auth profiles is a tool, named after the command with underscores (products integrations list → products_integrations_list), and sends exactly the same request.

Requirements: Node.js 18+ (check with node --version), an Outrank API key from https://www.outrank.so/dashboard/settings/api-keys, and an organization on the current Outrank app version. The same guide is on the web at https://www.outrank.so/docs/mcp.

Remote server

Outrank also hosts the same tools at https://www.outrank.so/api/mcp (Streamable HTTP), for clients that connect to a URL instead of starting a command, such as Claude, ChatGPT or Cursor. Sign in with OAuth when the client asks, or send an API key as Authorization: Bearer outr_live_....

• Claude Code plugin: /plugin marketplace add Outrank-SAS/outrank-cli, then /plugin install outrank@outrank.
• Gemini CLI: gemini extensions install https://github.com/Outrank-SAS/outrank-cli.
• Other clients: see llms-install.md. The hosted server always uses the auto toolsets, has no read-only switch and takes images as base64 only: it never reads a file. It is built from createRemoteMcpServer in src/adapters/mcp/remote.js, which takes the key, the Outrank origin and, optionally, the organization's auth whoami envelope so it does not ask for it again.

Claude Code

Run this in the project folder (macOS, Linux, WSL, or the Windows Command Prompt):

claude mcp add outrank --env OUTRANK_API_KEY=outr_live_xxx -- npx -y outrank-cli@latest mcp

If the server does not start on native Windows, use the cmd /c form:

claude mcp add outrank --env OUTRANK_API_KEY=outr_live_xxx -- cmd /c npx -y outrank-cli@latest mcp

In PowerShell, call claude.exe instead of claude (claude.cmd when Claude Code was installed with npm), so that the -- separator is kept.

Check the connection with claude mcp get outrank, then start a new Claude Code session. That command prints the stored key, so do not paste its output anywhere.

To share the server with a team, commit a .mcp.json that takes the key from each developer's environment, so no key lands in git:

{
  "mcpServers": {
    "outrank": {
      "command": "npx",
      "args": ["-y", "outrank-cli@latest", "mcp"],
      "env": { "OUTRANK_API_KEY": "${OUTRANK_API_KEY}" }
    }
  }
}

Each developer then sets the variable once:

# macOS, Linux: add this line to ~/.zshrc or ~/.bashrc
export OUTRANK_API_KEY=outr_live_xxx

# Windows, from the Command Prompt or PowerShell
setx OUTRANK_API_KEY outr_live_xxx

The variable reaches new terminals only, so open a new one before starting Claude Code.

Cursor

Add the server to ~/.cursor/mcp.json, the file for all projects (on Windows: %USERPROFILE%\.cursor\mcp.json). It is in your home folder, outside any repository, so the key in it cannot be committed by accident:

{
  "mcpServers": {
    "outrank": {
      "command": "npx",
      "args": ["-y", "outrank-cli@latest", "mcp"],
      "env": { "OUTRANK_API_KEY": "outr_live_xxx" }
    }
  }
}

If the server does not start on native Windows, use "command": "cmd" and "args": ["/c", "npx", "-y", "outrank-cli@latest", "mcp"].

For one project or a team, put the server in .cursor/mcp.json inside the project and take the key from the environment, so the file can be committed without it:

{
  "mcpServers": {
    "outrank": {
      "command": "npx",
      "args": ["-y", "outrank-cli@latest", "mcp"],
      "env": { "OUTRANK_API_KEY": "${env:OUTRANK_API_KEY}" }
    }
  }
}

Set OUTRANK_API_KEY as shown in the Claude Code section, then quit and reopen Cursor. A project server may first have to be switched on in the MCP section of the Cursor settings; a server in the all-projects file starts on its own.

Never commit a file that contains the key. A key written into a project file can end up in git with the next commit: keep the key in the all-projects file or in the environment. If a key was committed, revoke it at https://www.outrank.so/dashboard/settings/api-keys and create a new one. If Cursor does not see the variable, which can happen on macOS when it is started from the Dock, every call returns CLI_AUTH_REQUIRED: use the all-projects file instead.

Other MCP clients

Any client that can start a local MCP server (the stdio transport) works. Give it these three values; many clients read the same JSON as the Cursor example above.

• Command: npx
• Arguments: -y outrank-cli@latest mcp
• Environment variable: OUTRANK_API_KEY set to your API key

The examples use the latest tag, so the server picks up each new release the next time the client starts it. To stay on one version, replace latest with an exact version number from the npm page. If you install the package globally (npm install -g outrank-cli), the command is outrank-cli mcp, or the outrank-mcp binary.

Options

--api-key, --base-url and --allow-custom-base-url are not accepted by mcp. A command line the server cannot use (an unknown option, a mistyped toolset name) does not stop it and does not quietly change what it does: it starts, and every tool call returns the problem so the assistant can tell you what to fix.

Toolsets

Tools are grouped into toolsets: core, integrations, gsc, linking, backlinks, keywords, articles, improvements, marketplace-seller, marketplace-buyer, billing, blog, ai-cited-lists.

With the default auto, the server asks Outrank at startup which toolsets the organization can use (entitlements in auth whoami) and lists only those, so a marketplace buyer without an Articles subscription does not see dozens of tools that would only return errors. A toolset the organization can only read (for example after a subscription ended) lists its read tools only. A toolset Outrank could not verify (unverified_toolsets) stays listed. The tools that start a new area (marketplace seller and buyer setup, backlink subscription quotes, the billing portal link, the product-slot quote and the AI-Cited Lists status) are always listed. Typical sizes: 33 tools for a new organization, 245 with everything enabled. ai-cited-lists is listed only for organizations with a product on the Backlinks Enterprise plan.

auto is a noise filter, not a permission system: Outrank checks access on every request whatever the tool list says. If the lookup fails or takes longer than three seconds, the server starts with core plus the setup tools, says so in its instructions, and refreshes the list as soon as a lookup succeeds. After a tool that changes what the organization can use succeeds (products_create, products_pause, products_resume, billing_purchase_products_buy, marketplace_buyer_checkout, marketplace_buyer_change_plan and the seller onboarding tools), the server re-reads the organization in the background and tells the client when the tool list changed; auth_whoami refreshes it on demand. A service the human buys in the dashboard shows up on the next auth_whoami or restart.

When a tool you need is missing, either the organization does not have that service yet, or the list was narrowed by configuration. --toolsets all lists everything; --toolsets core,keywords,articles lists exactly those toolsets and nothing else, so include core unless you already know your product ids. --read-only and an explicit --toolsets list are enforced when a tool is called, not only when tools are listed.

--read-only means nothing in Outrank or on your site changes. A few read tools still send data to Outrank to get an answer: price quotes, checks of third-party credentials (products_integrations_validate, the Webflow and Framer discovery tools) and keyword metric lookups.

Organizations and profiles

An API key belongs to one organization, and one server instance works on one organization. Every tool result repeats it under organization (id, user_email, profile, base_url), so the assistant cannot mix organizations up silently.

Besides tools, the server offers five prompts for clients that support them — onboard_product, plan_keywords (product_id, optional days), improve_declining_articles (product_id), setup_ai_cited_lists (product_id) and setup_publishing_integration (product_id, optional provider) — each a step-by-step brief naming the tools to call, listed only while its toolset is on and never in read-only mode; and one resource, outrank://whoami, a JSON document with the organization, the known entitlements and the toolsets in use, which a client can read without spending a request.

Outrank writes its agent_guidance for the HTTP API, naming endpoints such as GET /api/agent/v1/products/<id>. The server rewrites those references into tool references the assistant can call — products_get {"product_id":"<id>"} — using the registry that maps every tool to its endpoint. Query values become typed arguments (?limit=5 → {"limit":5}). An endpoint it cannot map is passed through unchanged, and so is one whose values the tool would refuse (an unknown filter, a provider that tool does not take) or whose query or path continues with text the rewrite cannot read (?email=a@b.com, ?q=%ZZ). The purchase endpoint is named as its two steps in order: billing_purchase_products_quote, then billing_purchase_products_buy. A rewritten reference can name a tool the server configuration leaves out; calling it returns an error saying which toolset to add. The guidance written by the CLI itself already names tools on this surface.

For several organizations, store one profile per organization with the CLI and register one server per profile:

outrank-cli auth login outr_live_xxx --profile acme
outrank-cli auth login outr_live_yyy --profile globex
claude mcp add outrank-acme -- npx -y outrank-cli@latest mcp --profile acme
claude mcp add outrank-globex -- npx -y outrank-cli@latest mcp --profile globex

A selected profile ignores OUTRANK_API_KEY, so both servers stay on their own organization even when that variable is exported in your shell. In PowerShell, call claude.exe in the last two commands, as described under Claude Code.

Security

• The key never passes through the assistant. No tool takes a key, a base URL or a profile as an argument, auth login is not a tool, and auth_status shows neither the key nor the config path. Set the key in the client configuration, in the environment or with outrank-cli auth login in a terminal; do not paste it into a chat and do not put it in a file that is committed.
• The key is only sent to Outrank. The server accepts www.outrank.so and outrank.so. Any other base URL is accepted only when the key and the URL come from the same stored profile, which you create yourself in a terminal (outrank-cli auth login <key> --profile staging --base-url <url> --allow-custom-base-url, then mcp --profile staging). Environment variables cannot unlock another host, so a .mcp.json from a repository you do not control cannot redirect your key by setting OUTRANK_BASE_URL. Redirects are never followed.
• Tools that cost money or cannot be undone are flagged (destructiveHint), so the client asks before running them. A client set to approve tools automatically removes that safeguard.
• Purchases take two deliberate steps. billing_purchase_products_buy charges the stored card: it requires the amount from a preceding billing_purchase_products_quote and an idempotency_key. If that call times out, it must be retried with the same key and arguments: Outrank records the outcome per key and returns it again (data.replayed is true), while a new key can charge twice. marketplace_buyer_change_plan cancels immediately for cancel_subscription and cancel_scheduled, and is refused without a confirm_subscription_id, which the assistant is told to read from marketplace_buyer_subscription. These fields stop a single careless call; they are values the assistant can obtain itself, so they do not replace the approval prompt of your client.
• Uploads are restricted. An image must be inside the upload directory (symlinks are resolved first), at most 5 MB, and its bytes must match its .jpg, .jpeg, .png, .webp or .gif extension. A path outside the directory is refused before the file system is touched, so nothing else on disk can be sent or probed. Point --upload-dir at a folder that holds only the images you want to publish.
• A write that did not get an answer is never reported as safe to repeat. When a timeout or a dropped connection hits a tool that changes something, the result says the outcome is unknown and to check first; for publishing and generation tools it names the tool to poll.
• Only register this server from a configuration you trust. Whoever controls the server's command line and environment controls the process: the checks above protect your key against a redirected base URL, not against a configuration that replaces the program or its runtime options.
• Third-party tokens are visible in the conversation. Connecting Webflow, Framer, Ghost, Shopify, Wix or a webhook means passing that platform's token as a tool argument. Use a scoped token you can rotate.
• Marketplace text is untrusted. Notifications, placement briefs and placement articles are written by other organizations. The MCP server returns each such field as { "untrusted_counterparty_text": "…" } instead of a plain string (notification titles and bodies; the keyword, anchor text, target URL, article title and publish error of a hosted placement; the title, keyword, meta description, slug, instructions, publish error and summary of the articles in marketplace_seller_content_history; the article title, URL, image URL and seller site of a bought placement; the seller site and article title in the credit history; and the placement article itself: title, content, image URL, meta description, slug, keyword, section heading and seller site), so an assistant can tell it apart from Outrank's own fields, and tells the assistant to treat it as data, not instructions. The same wrapping covers the AI-Cited Lists tools: list titles, URLs and hosts, entry names, owner contacts and replies, ChatGPT answer excerpts and source URLs, and cited page titles, URLs and domains in ai_cited_lists_overview, ai_cited_lists_lists_list, ai_cited_lists_outreach, ai_cited_lists_offers_get, ai_cited_lists_wins_get and ai_cited_lists_citations_summary. The CLI returns the plain strings. The articles_* tools return a hosted marketplace article next to the organization's own articles: each article carries is_marketplace_placement, and when it is not false its title, keyword, meta description, slug, instructions, publish error, image URL, summary, body and replace excerpts are wrapped the same way, while the organization's own articles stay plain. This covers every articles_* tool that returns article text, articles_delete included. For articles_retry_publish, articles_generate, articles_precreate, articles_upload_image and articles_upload_featured_image the flag sits at the top of the result and also decides the fields beside the article: the publish error of a failed retry, the keyword, and the alt text, file name and address of an uploaded image. A result without the flag is wrapped. When a tool takes such text back (articles_update, articles_update_content), pass the plain string, not the wrapped object; the tool names the field if it gets the object.
• Rate limits are shared. The server uses the same per-minute and per-day budget as every other client of that key. It paces its own requests to Outrank's limit of 120 per minute, lowers that budget when a response reports fewer remaining requests, and waits out a Retry-After, so a client that fans out many tool calls at once gets them queued instead of rejected; a queued call still counts against the client's own tool timeout.

Troubleshooting

• The server does not start. Run the same command in a terminal: npx -y outrank-cli@latest mcp --help must print usage. Check that Node.js 18 or newer is installed (node --version). On native Windows, if the client cannot start npx directly, use the cmd /c npx … form.
• The command works in a terminal, but the client cannot find npx or node (macOS, Linux). A client started from the Dock or a desktop menu does not always get the PATH of your shell, so a Node.js installed with nvm, fnm or volta can be invisible to it. Run which npx in a terminal, use that full path as the command, and add its folder to PATH in the env block of the server entry, for example "PATH": "/home/you/.nvm/versions/node/v22.0.0/bin:/usr/bin:/bin". The full path alone is not enough: npx starts node through PATH.
• PowerShell reports unknown option '-y' on claude mcp add. PowerShell drops the -- separator when claude is a script or a function instead of the program itself (an npm-installed Claude Code, or a wrapper in your profile). Call claude.exe mcp add … (claude.cmd when Claude Code was installed with npm) or run the command from the Command Prompt.
• The first start is slow, or the server fails to connect. npx downloads the package the first time and contacts the npm registry on every start, so an empty cache or a slow registry can push startup past the client's limit. In Claude Code, run /mcp reconnect all to try again; MCP_TIMEOUT (milliseconds) raises the startup limit. To take the registry out of the startup path, install the package globally (npm install -g outrank-cli@latest) and use outrank-cli mcp as the command.
• Every call returns CLI_AUTH_REQUIRED. The server has no key. Add OUTRANK_API_KEY to the server entry, or select a stored profile with --profile.
• Only a few tools are listed. Read the server instructions in the client: they name the toolsets that are off and why. See Toolsets.
• A long call times out. improvements_analyze, improvements_candidates_brief, improvements_tasks_execute, improvements_executions_push, articles_generate, articles_precreate, articles_retry_publish, keywords_generate and ai_cited_lists_entry_generate can run for minutes. When the call does not finish, the result is CLI_OPERATION_MAY_STILL_BE_RUNNING and names the tool to poll: the work continues on the server, so poll instead of repeating the call. The server sends progress notifications while such a call runs, but clients do not have to extend their own limit because of them. Claude Code does not cut a tool call off by default: MCP_TOOL_TIMEOUT (milliseconds) is about 28 hours when unset, and a timeout field on the server's .mcp.json entry sets a hard limit for that server which progress notifications do not extend. Cursor (measured on 3.22) stops a call after 120 seconds without a progress notification and keeps waiting while they arrive, so long calls get through there. Other clients may stop after a fixed time whatever the server does; the poll tools are the way through.
• The client warns about too many tools. Some clients cap or warn above a few dozen tools. Narrow the list with --toolsets, for example --toolsets core,keywords,articles.
• Staging or a local deployment. Store a profile for it in a terminal (see Security) and start the server with --profile <name>.
• See what the server does. Set OUTRANK_MCP_DEBUG=1; one line per tool call is written to stderr, which the client shows in its MCP logs.

Tools

Tools that take a JSON body describe its fields in their description; products_create, products_update, products_output_settings_update, keywords_add, articles_update, articles_update_content, improvements_settings_update and ai_cited_lists_settings_update also declare them in the input schema (types, allowed values, and for products_create the required fields), so a body with a missing required field or a wrong type is refused before any request. Unknown keys are passed through; Outrank decides about them. The same checks apply to --json on the CLI.

Generated from the command registry with npm run docs:tools. The registry is checked against the Outrank server's route list in tests/fixtures/agentApiSurface.json, refreshed from a checkout of the Outrank app with npm run surface:extract -- <path-to-outrank-repo>: a server route without a tool, a tool without a server route, a guidance sentence naming an endpoint the server cannot map to a tool, or a rewritten argument the named tool would refuse fails the tests. The fixture records the server commit and, as sourceDirty, whether that checkout had uncommitted changes in the files it reads; extract again from a clean checkout before a release. To see whether the fixture is stale, run node scripts/extractAgentApiSurface.js --check <path-to-outrank-repo>, or run the tests with OUTRANK_SERVER_DIR=<path-to-outrank-repo>: both list the routes and guidance mentions that differ, and without the variable that one test is skipped. Kinds: read changes nothing; write changes Outrank or the connected site; destructive deletes or cannot be undone; money changes what the organization pays; local makes no request. Tools marked ★ are always listed in auto mode.

246 tools.

Documentation truncated — see the full README on GitHub.