Connect SEOReport to Gemini CLI: MCP setup for SEO audits

What you need

You need an active SEOReport plan and an API key. Create the key at https://seoreport.dev/dashboard/api-keys. API keys require an active plan. [3][4][1]

SEOReport shows the key once. Store it in a secret store or an environment variable, not in a prompt, a project file or your shell history. [4]

The server speaks streamable HTTP at https://seoreport.dev/mcp. It expects the key on every request as an Authorization: Bearer <api-key> header, the same key you use for the REST API. [3][4][1]

Add the server

Add an mcpServers entry to ~/.gemini/settings.json (user) or .gemini/settings.json (project). Use httpUrl, the field for streamable HTTP, and send the key in headers. [5][6]

{
  "mcpServers": {
    "seoreport": {
      "httpUrl": "https://seoreport.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SEOREPORT_API_KEY}"
      }
    }
  }
}

String values in settings.json can reference environment variables with $VAR_NAME, ${VAR_NAME} or ${VAR_NAME:-DEFAULT_VALUE}. [6]

We do not show the gemini mcp add --header form: your shell would substitute the key, so it would sit on a command line while the command runs and the settings file would hold the key itself. [5]

Confirm it works

Run gemini mcp list to see each server's configuration and connection status. Inside a session, /mcp lists the servers, their status and their available tools. [5]

You should see 9 tools whose names start with seoreport_: seoreport_create_report, seoreport_get_report_status, seoreport_get_report, seoreport_list_reports, seoreport_get_report_download, seoreport_get_account, seoreport_list_plans, seoreport_start_checkout and seoreport_submit_feedback. [3]

Then try a first prompt: "Audit https://example.com and list the three highest-severity findings." The agent can start the audit with seoreport_create_report and read the findings with seoreport_get_report. A report takes up to about 30 seconds. [4][3]

A new site uses one credit from your plan. Running a site you already have a report for again does not use a credit. [1][2]

Keep the key out of version control

Gemini CLI's docs advise against hardcoded secrets and point to variable expansion instead. Reference ${SEOREPORT_API_KEY} in settings.json and set the variable in your shell profile. [5][6]

Keep a server that carries the key itself in the user file, ~/.gemini/settings.json, outside the repository. A project .gemini/settings.json lives in the project folder. [5]

Leave the trust option off. When it is true, Gemini CLI bypasses every tool-call confirmation for the server. [5]

Troubleshooting

Authentication error or HTTP 401: SEOReport lists and calls tools only for a valid key. Check that the header value is Bearer, one space, then the key. If the key may be wrong or exposed, revoke it and create a new one in the dashboard. [3][4]

Check that the entry uses httpUrl. With url, Gemini CLI treats the address as an SSE endpoint. [5][6]

Plan or credit error: if seoreport_create_report says an active plan is required or the month's credits are used, the key works but the account cannot start a report. Ask the agent to call seoreport_get_account to see the plan and the credits left. [4]

To subscribe from the agent, it can call seoreport_list_plans and then seoreport_start_checkout. Checkout returns a browser link: an agent can start it, and only a person can pay. Credits reset on the first day of each month (UTC). [4][1]

Tools not listed: run /mcp to see the server's connection status and discovery state, or gemini mcp list for its configuration. [5]