🇬🇧 English · 🇷🇺 Русский

Keys.so MCP

Turn competitor data into your next SEO investigation.

Ask which keywords a competing domain ranks for, inspect its ads or explore its backlink sources. Keys.so MCP brings supported Keys.so reports into your assistant, so you can ask follow-up questions against the same source data instead of preparing a new export for each question.

Quick start · Connect your assistant · Issues

Try asking your assistant:

Get the organic keyword report for example.com. Group the returned queries by topic and suggest which groups deserve a closer look.

What you can do

Quick start

Prefer a ready package? Install the release and generate your client configuration. No source checkout is required.

Install Python 3.12–3.14 and uv. Clone with Git or download the ZIP. With a ZIP, open the extracted directory and skip the first two commands.

You need a Keys.so API token and access to the reports you want to use. The wizard saves the token in a private local file.

git clone https://github.com/zai-one/keysso-mcp.git
cd keysso-mcp
uv sync --frozen
uv run --frozen python scripts/configure.py
uv run --frozen keysso-mcp --config mcp.local.json --check-config

The wizard creates a local configuration and stores secrets in private files. It refuses to overwrite an existing setup. --check-config validates local settings; the first request below checks your account connection.

Connect your assistant

Add this configuration to an MCP client that uses mcpServers, such as Claude Desktop or Cursor. Replace /ABSOLUTE/PATH/ with your absolute path; Windows JSON paths can use forward slashes, such as D:/Tools/.

{
  "mcpServers": {
    "keysso": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/keysso-mcp",
        "run",
        "--frozen",
        "keysso-mcp",
        "--config",
        "/ABSOLUTE/PATH/keysso-mcp/mcp.local.json"
      ]
    }
  }
}

The client starts the MCP server for you. Refresh its tool list, then make your first request. For clients with a different config format, reuse the same command and args; uv must be available to the client process.

First request

Open keysso://reports and show me which reports are available. Then retrieve the domain overview for my site.

The catalogue lists supported reports and parameters without spending an API request. A domain query returns Keys.so data using your token. Supply your domain and the database/region you want to analyse.

If tools do not appear, check the absolute path, whether the client can find uv, and the --check-config result. For access errors, check account credentials and permissions. Installation and troubleshooting.

Access and limits

Use keysso_domain_report for keywords, competitors, pages or backlinks, and keysso_compare_domains for overlaps and gaps. Each can collect up to five pages and return JSON or CSV with source and completeness fields. The original keys_so_query still requests one page. Report examples and limits.

Ask: “Export a competitor’s keywords excluding my domain, in CSV. Show whether the sample is complete.”

This server exposes read-only reports. Available data and request limits depend on your Keys.so account. See request limits and access settings.

Authenticated HTTP is available for a server deployment. See HTTP setup, configuration and permissions and Python package integration.

uv sync --frozen --all-groups
uv run --frozen python scripts/verify.py
uv run --frozen python scripts/verify_install.py

Tests use synthetic fixtures. A passing test run does not establish live provider connectivity.

Built by ZAI.ONE

ZAI.ONE is a digital agency working on websites, SEO, advertising and analytics. We also build tools that connect AI assistants to everyday work. Talk to us on Telegram about setup, automation or an integration for your team.

Use and feedback

You may install and use this project for your own accounts under LicenseRef-ZAI-ONE. This is not an open-source license. Third-party notices remain in NOTICE. If it helps, give the repository a ⭐. Missing something or found a bug? Open an issue. I'm working on this project; accepted improvements are implemented here. Support is not guaranteed.