Research keywords through OpenSEO MCP

By

Updated

Tagged: SEO, AI

Connect OpenCode to OpenSEO, verify the project and search market, approve a bounded keyword lookup, and save only the ideas you select.

OpenSEO’s MCP server lets a coding agent research keywords and save the useful ones in a project. You can give the agent the business context, look at the numbers it returns, and pick the ideas worth pursuing.

We’ll connect OpenCode, check the existing project, then prepare one small research request. The setup doesn’t need a paid query. Fresh research comes later, after you approve its scope and cost. I didn’t run one for this tutorial, so you won’t find volume or difficulty numbers here.

My OpenSEO guide explains the application and its data providers. Here we’ll follow the actual tool workflow for a hypothetical reading-club app.

Connect the hosted server

You need an OpenSEO account and an existing project. OpenSEO’s MCP setup guide gives this hosted endpoint:

https://app.openseo.so/mcp

In the directory where you use OpenCode, add it with the current CLI:

opencode mcp add openseo --url https://app.openseo.so/mcp
opencode mcp list

If it needs authentication, run:

opencode mcp auth openseo

Complete the OpenSEO login and inspect the access you’re granting. You can also open OpenCode, enter /mcps, and select the server to authenticate. OpenCode’s MCP documentation covers the other options.

If you prefer a configuration file, the equivalent server belongs in opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "openseo": {
        "type": "remote",
        "url": "https://app.openseo.so/mcp"
      }
    }
  }
}

Current OpenCode uses mcp.servers. Older examples place named servers directly under mcp, which is a different configuration shape.

OAuth keeps the access credential out of this project file. OpenSEO also supports personal API keys for clients that need them. Use the client’s environment-variable substitution for that route, and don’t save the key in JSON or paste it into a prompt. A DataForSEO credential goes in the OpenSEO installation’s provider setup, not in the MCP connection.

Read the project before researching

Start with this request:

Use OpenSEO. Call list_projects and show me the available project names,
organizations, domains, locationCode, and languageCode.
Do not create or update anything and do not run paid research.

Choose the intended project from the returned list. The tools use its actual id as projectId; don’t ask the agent to invent an ID from the project name.

Then ask it to call get_project_context and list_saved_keywords for that project. These provide existing business context and saved ideas, without buying fresh market data.

The project-list tool returns default market settings. Check them carefully. An English-language app aimed at the United States needs different research settings from an Italian-language local club.

For the example below, the intended country is the United States (2840) and the language is English (en). Confirm those settings in the project before proceeding. Keep them with the results so later comparisons use the same market.

Fig 1 · 1/4Read, research, then save
Choose the actual returned project ID

Prepare one paid operation

OpenSEO’s research_keywords tool accepts one to five seeds. Each seed is researched independently. Its supported resultLimit values are 150, 300, and 500.

A request for a ten-keyword shortlist can therefore retrieve up to 150 results and select ten afterward. resultLimit: 10 isn’t an accepted value.

Ask the agent to prepare the request before executing it:

For the selected reading-club project, prepare one research_keywords call.
Use one seed: "book club app".
Set locationCode to 2840 and languageCode to "en" on that seed.
Set resultLimit to 150, includeClickstreamData to false,
and groupKeywords to false. Do not add a local-area locationName.
Show the intended request and current cost information, including possible
fallback costs. Wait for my approval before running it.

Fresh research consumes provider usage or hosted credits. The tool can perform fallback work internally, so one MCP call doesn’t necessarily mean one upstream provider request. Clickstream refinement can also change the cost.

A prompt limits what you’re asking the agent to do. Enforce a financial ceiling through the provider or application account controls where available. If you can’t set a limit you’re comfortable with, don’t run it.

After checking the current terms, you can approve that single prepared call. Keep any follow-up expansion as a separate request.

Read the returned evidence

The response can contain a successful result or an error for each seed. Have the agent show the source, market, and whether fallback work occurred before interpreting the keyword rows.

Ask for a shortlist based on the app’s actual purpose. For a reading-club organizer, a phrase about scheduling group discussions may fit better than a high-volume search for book summaries.

Treat missing metrics as missing. A null difficulty value doesn’t mean zero difficulty. Keep the provider’s estimates separate from evidence about your own website, such as Search Console clicks. I read those clicks in SEO Bot.

Use the model’s explanation to judge relevance, and check that it leaves the empty fields empty.

Save the keywords you choose

Researching and saving are separate operations. After reviewing the shortlist, name the phrases you want retained and ask the agent to call save_keywords.

Have it use the same projectId, locationCode, and languageCode. If it saves metrics, it should copy the returned fields for the matching keyword. Don’t let it substitute estimates from memory.

Saving existing research doesn’t make a DataForSEO request. Tags can change shared organization in the project, so leave them out unless you’ve chosen how to apply them.

Finally, call list_saved_keywords again and check the rows in OpenSEO’s interface. You should be able to find the selected phrases in the intended market without rerunning paid research. The next session can read that record before it proposes another lookup.

Want me to talk about your product? You can sponsor this site.

Related posts about seo: