MCP tools reference

The server is at http://127.0.0.1:7420/mcp (Streamable HTTP) and needs Authorization: Bearer <your token> on every request. It listens on your Mac only. Web pages in a browser are refused, even with the right token.

An agent refers to an app by the id from list_tracked_apps, or by its name or store app id. A name shared by several tracked apps (the same product on iPhone and Android) matches them all. find_gems searches each; the tools that change one app ask for its id, or a platform.

Tool	What it does	Needs an active license
list_tracked_apps	The apps tracked on this Mac, with platform, storefront and tracked keyword count	No
keyword_metrics	Popularity and difficulty for up to 100 terms on a platform in a storefront (either store), plus an app’s rank	Only for keywords not already on this Mac
rank_history	How the app’s rank, popularity and difficulty changed over days (default 30) for tracked keywords. placesGained is positive when the app moved up	No
suggest_keywords	Candidates from a seed and/or a tracked app, with metrics where known, marked tracked	Yes
find_gems	Untracked suggestions that pass your gem rules (default: popularity at least 20 and at least 10 above difficulty)	Yes
track_keywords	Track terms for an app, optionally with a tag, and fetch their metrics	Yes
tag_keywords	addTags, removeTags or replace notes on tracked keywords	Yes
export	Tracked keywords with the metrics this Mac holds, as json or csv	No

Keywords Keywordee hasn’t stored yet come back pending. Ask again in a few minutes.

Fair use

Calls that reach Keywordee’s service count against the license’s daily fair-use limits exactly as the app’s own do. Hitting one returns fair_use_cap_reached, with the cap and when it resetsAt.

When your license has lapsed or is disabled

Tools that only read what’s already on your Mac keep working. The others return an error with the code licence_lapsed or licence_disabled and a message your agent can show you, or not_activated if this Mac isn’t activated. keyword_metrics answers keywords it already holds and refuses only when it would have to fetch.

Errors

A failed call comes back as a tool result with isError: true and {"error": {"code": …, "message": …}}. Other codes: invalid_arguments, app_not_found, ambiguous_app, keyword_not_tracked and service_unavailable.

What the server refuses

• No token, or the wrong one: 401.
• Any request that carries an Origin header, which is what a web page sends: 403.
• A Host header that isn’t 127.0.0.1, localhost or [::1] on the served port: 403.
• GET and DELETE: 405. There is no event stream.