Troubleshooting and limitations#

Start with wdkg status (or the kg_status tool). It makes no network calls and shows the endpoints, whether a Google key is present and where it came from (never the value), cache statistics and limits. wdkg status --live additionally checks that the Wikidata MCP service answers.

Common problems#

The MCP server does not appear in my client. The first start downloads the package and its dependencies, which can take longer than a client's default start-up timeout. Run the uvx ... command from Installation once in a terminal with --version to warm uv's cache, then restart the client. In Codex, set startup_timeout_sec = 60.

Running wikidata-google-knowledge-mcp in a terminal just waits. That is expected: it is a stdio server waiting for an MCP client. Use --help for a setup note, or use wdkg for terminal work.

"error": "not_configured" for Google. Google is optional. The message tells you where to put GOOGLE_KNOWLEDGE_GRAPH_API_KEY; Wikidata keeps working without it. Desktop clients often do not pass your shell environment, so the secrets file (~/.config/wikidata-google-knowledge-mcp/secrets.env) is the reliable place.

HOLD with NO_LOCAL_ANCHOR. The name matched but nothing you supplied pins it to one entity. Add an anchor: official website, coordinates, address, date plus venue for events, creator for works. A city alone is supporting context, not an anchor, for places.

AMBIGUOUS with MULTIPLE_ANCHORED_CANDIDATES. Your anchor fits more than one item, typically an institution and its building. Add a more specific anchor (usually the official website) or choose from candidate_ids yourself.

NO_CANDIDATE. The bounded search found nothing usable under that name. Try the name as Wikidata labels it, add aliases, or set lang. It is not proof that no item exists.

A batch stopped with budget_exhausted. Raise --max-wikidata-requests and run the same command again; finished rows are skipped.

Results look stale. Wikidata values are cached for 7 days by default. Use --no-cache for one call, wdkg cache clear to empty the cache, or WDKG_CACHE=0 to disable it.

uvx cannot find the package or version. Check the spelling wikidata-google-knowledge-mcp and that your package index is PyPI. As a fallback, install from the GitLab release tag (Installation); that path needs git on your PATH.

What leaves your machine#

Entity names and the parameters of each lookup go to Wikidata services: the Wikidata MCP service on Wikimedia Cloud (wd-mcp.wmcloud.org) for interactive calls, and the Wikidata Action API and Query Service for batch resolution.
They go to Google only when you configured a key and asked for Google (or the resolver's policy calls it; see Installation).
Place and type hints for kg_search are checked locally and never sent.
There is no telemetry and no server operated by this project.

What is stored locally#

A SQLite cache in ~/.cache/wikidata-google-knowledge-mcp/ (Wikidata values expire after 7 days by default).
For the resolver, a decision and evidence store in the same directory.
Google responses are cached only as long as their Cache-Control header allows. The Knowledge Graph Search API currently sends none, so nothing received only from Google is stored.

Provider limitations#

Coverage. Wikidata is broad but uneven: small venues, recent events and local organizations are often missing or lack an official website or coordinates, which is exactly what the resolver needs to decide. Expect more HOLD for them.
Freshness. Items change. A cached answer can be up to the cache TTL old.
Availability. The public Wikidata services have rate limits and occasional outages; errors are reported per call or per row and never cached as "no result".
Google. The Knowledge Graph Search API is not a places or maps API and not a full export of Google's Knowledge Graph. Its quotas, terms and availability are Google's.
Not official. This project is independent and not affiliated with the Wikimedia Foundation, Wikimedia Deutschland or Google.

Security#

Report vulnerabilities through a confidential issue as described in SECURITY.md. The Google key is read from the environment or a local file, sent only in the X-Goog-Api-Key header and redacted from all output.