
wikidata-mcp-server
io.github.cyanheads/wikidata-mcp-server
Search and fetch Wikidata entities, execute SPARQL queries, and resolve external identifiers.
Documentation
@cyanheads/wikidata-mcp-server
Search and fetch Wikidata entities, execute SPARQL queries, and resolve external identifiers via MCP. STDIO or Streamable HTTP.
Public Hosted Server: https://wikidata.caseyjhand.com/mcp
Overview
Wikidata's knowledge graph. Search and fetch entities, traverse the graph with SPARQL, and resolve external identifiers like DOI, PMID, ORCID, OpenAlex, and IMDb to their Wikidata items. No API key required.
Tools
| Tool | Description |
|---|---|
wikidata_search_entities | Search for items or properties by text query, returning QIDs/PIDs with labels, descriptions, and match metadata |
wikidata_get_entity | Fetch a full entity by QID or PID with optional field and language filtering |
wikidata_get_labels | Batch-resolve up to 500 QIDs or PIDs per call to human-readable labels and descriptions |
wikidata_get_statements | Fetch property claims for an entity with qualifier detail, per-property paging, a best-rank filter, and QID and PID label resolution |
wikidata_get_sitelinks | Fetch Wikipedia and Wikimedia project article URLs for a Wikidata item |
wikidata_sparql_query | Execute a SPARQL SELECT query against the Wikidata Query Service |
wikidata_resolve_external_id | Look up a Wikidata entity by an external identifier (DOI, PubMed ID, ORCID, OpenAlex ID, etc.) |
Resources
| Resource | Description |
|---|---|
wikidata://entity/{id} | Compact markdown summary of a Wikidata entity — labels, English description, instance-of, Wikipedia link, image, and the number of properties with statements |
All resource data is also reachable via tools.
The published wikidata-guide covers entity disambiguation, qualified statements, external identifiers, and SPARQL. It is included in plugin installs and served over MCP as skill://wikidata-guide/SKILL.md.
Capability reference
wikidata_search_entities tool
- Searches labels, aliases, and descriptions;
type="item"for people, places, and works,type="property"for P-IDs - Takes a Wikidata language code (
en,de,pt-br; case-insensitive);limitdefaults to 10 and serves up to 500 per page - The endpoint returns no total: page by sending each page's
nextOffsetasoffset(0–9,999) until a page returns no results or nonextOffset; only the first 10,000 results are reachable - Each hit includes match metadata saying whether it matched a label or alias
wikidata_get_entity tool
- Q-IDs (e.g.
Q76) fetch items and P-IDs (e.g.P31) fetch properties;fieldsselectslabels,descriptions,aliases,statements, orsitelinks, and narrows the upstream fetch idmay be bare, an entity URI (http://www.wikidata.org/entity/Q76), orwd:Q76, as onwikidata_get_labels,wikidata_get_statements, andwikidata_get_sitelinkslanguagesfilters multilingual maps to the given language codes- An entity too large to inline returns an outline of field categories with byte sizes; its
retrieval_noticenames afieldsset that fits and points oversized statements or sitelinks to the tool that can narrow them
wikidata_get_labels tool
- Up to 500 distinct IDs per call via the MediaWiki
wbgetentitiesAPI (batched 50 at a time), with up to 50 language codes per request;idstakes up to 10,000 entries, and distinct IDs past the first 500 come back indeferredIdsto send in a follow-up call - IDs may be bare (
Q76), entity URIs (http://www.wikidata.org/entity/Q76), orwd:Q76, the forms SPARQL results carry - Reports a
foundcount andnotFoundIDs for partial results; malformed entries come back ininvalidand fail the call (invalid_ids) only when no valid ID remains - Meant to follow a SPARQL query: run it, then humanize the QIDs
wikidata_get_statements tool
propertieslimits the fetch to specific P-IDs (omit for all); item QIDs and quantity units in values, qualifiers, and references are resolved to labels unlessresolve_labels=false, and every P-ID the statements name is labelled inpropertyLabelsrank="best"keeps each property's preferred statements, or its normal ones when none is preferred, and never deprecated ones: the statements SPARQL's truthywdt:reads (default"all")- Each property returns up to
limitstatements (default 10, at most 500) fromoffset, in upstream order;propertyTotalscounts every statement a property holds, andnextOffset, present while any property holds more, continues every property at once - References stay grouped by source; unknown or absent values come back as
somevalue/novalue - A page of several properties too large to inline returns an outline of P-IDs with byte sizes, largest first (as of 2026-11-15, unfiltered Q30 carries 475 properties across 1,766 statements); re-call with the same
limit,offset, andrankpluspropertieswhose sizes sum to 24,000 or less, as theretrieval_noticesuggests. A single property is never outlined: it returns its window
wikidata_get_sitelinks tool
- Maps site codes (e.g.
enwiki) to article titles and URLs;sitesfilters to specific codes wikis_only=truekeeps only Wikipedia editions, those whose URL is on a<subdomain>.wikipedia.orghost (drops Commons, Wikispecies, Wikidata, Wiktionary, Wikiquote, Wikisource, and every other project)- Q-IDs only; P-IDs are not supported
wikidata_sparql_query tool
- Runs SELECT queries against the Wikidata Query Service (Blazegraph); ASK, CONSTRUCT, DESCRIBE, updates, and plain search text are rejected before the request is sent
- Standard prefixes (
wd:,wdt:,p:,ps:,pq:,wikibase:,bd:) and thewikibase:labelSERVICE (when the query uses a?<var>Label,?<var>Description, or?<var>AltLabelvariable) are added automatically;languagetakes one code or a fallback list likefr,en - Scholarly articles and their triples (DOI, PMID, authorship) live in a separate graph, reachable only inside
SERVICE wdsubgraph:scholarly_articles { … }(wdsubgraph:is predeclared); read an article's label inside that block withBIND(?paperLabel AS ?paperLabel)and a label SERVICE there - Results are SPARQL 1.1 JSON bindings, at most 4,000 rows per call; a larger result returns its first 4,000 with
truncated,shown,cap, and a notice to narrow theWHEREclause or aggregate, or, for a result not much larger, to page withORDER BYplusLIMIT/OFFSET(totalCountappears only when the whole result was read). A result body past 8 MiB fails asresult_too_large - Client
timeoutis 1–55s (server hard limit 60s); the Query Service allows each client (user agent and IP) 60 seconds of query processing time per 60 seconds and each IP at most 5 parallel queries
wikidata_resolve_external_id tool
- Resolves DOI (P356), PMID (P698), ORCID (P496), OpenAlex ID (P10283), IMDb ID (P345), and other external IDs to a QID; whitespace and resolver URL prefixes are stripped, and DOIs, PMIDs, ORCIDs, OpenAlex IDs, and IMDb IDs are normalized to their stored form
- The property must have data type
external-id; item-valued or media properties (e.g.P31,P18) are rejected - Searches the main graph and the scholarly-article graph (where scholarly articles and their DOIs and PMIDs live) in parallel; a graph that does not answer is named in
unavailableGraphs, and the result covers the other - Matches through statements of every rank, entities holding the ID at best rank first, then another non-deprecated rank, then deprecated;
match.rankreports the statement's rank (deprecatedusually means a retired or mistaken ID) - Returns
match=nullwhen not found (the Query Service lags the live wiki, so null is not proof of absence) andmultipleMatches(at most 5) when more than one entity claims the same ID; the label uses the requestedlanguage, falling back tomul
wikidata://entity/{id} resource
- Compact markdown summary — English label and description, the number of label languages with a sample of five, instance-of (
P31), enwiki Wikipedia link, image (P18), and the number of properties with statements - Returned as
text/markdown; for full entity data, usewikidata_get_entity idis a Q-ID or P-ID, the same identifiers the tools take
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
Wikidata-specific:
- Wikidata REST API v1 for entity and statement fetches — no SPARQL overhead for lookup operations
- MediaWiki
wbgetentitiesAPI for efficient batch label resolution - Wikidata Query Service (Blazegraph) for SPARQL with auto-injected prefix headers and label SERVICE
- A count input above its per-call cap is served at the cap with a notice;
WIKIDATA_CLAMP_LIMITS=falserejects it instead - Configurable
User-Agentper Wikimedia policy (WIKIDATA_USER_AGENT) - Separate timeout configuration for REST and SPARQL endpoints (
WIKIDATA_REST_TIMEOUT_MS,WIKIDATA_SPARQL_TIMEOUT_MS)
Agent-friendly output:
- All tools echo relevant input parameters in the response for traceability
wikidata_get_labelsdesigned to follow SPARQL result sets — run the query, then humanize in one callwikidata_resolve_external_idreturnsmultipleMatchesinstead of a false null when a Wikidata data-integrity issue puts duplicate claims on one external ID- Oversized entities and statement sets return a
kind: "outline"payload — field/property sizes plus aretrieval_noticenaming the exact re-call — instead of a truncated or oversized response
Getting started
Connect to the hosted instance, no install:
claude mcp add --transport http wikidata-mcp-server https://wikidata.caseyjhand.com/mcp
Or run it locally:
claude mcp add wikidata-mcp-server -- npx -y @cyanheads/wikidata-mcp-server
For other clients, add this to the MCP config file:
{
"mcpServers": {
"wikidata-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/wikidata-mcp-server"]
}
}
}
For Docker or a source build, see Running the server.
Configuration
All configuration is validated at startup via Zod schemas. Key environment variables:
| Variable | Description | Default |
|---|---|---|
MCP_TRANSPORT_TYPE | Transport: stdio or http | stdio |
MCP_HTTP_PORT | HTTP server port | 3010 |
MCP_HTTP_ENDPOINT_PATH | HTTP endpoint path where the MCP server is mounted | /mcp |
MCP_PUBLIC_URL | Public origin override for TLS-terminating reverse-proxy deployments | none |
MCP_AUTH_MODE | Authentication: none, jwt, or oauth | none |
MCP_SESSION_MODE | HTTP session mode: stateful, stateless, or auto | stateless |
MCP_LOG_LEVEL | Log level (debug, info, notice, warning, error) | info |
MCP_GC_PRESSURE_INTERVAL_MS | Opt-in forced-GC interval in ms (Bun only) | 0 (disabled) |
LOGS_DIR | Directory for log files (Node.js only) | <project-root>/logs |
STORAGE_PROVIDER_TYPE | Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1 | in-memory |
WIKIDATA_USER_AGENT | User-Agent string for Wikimedia requests (policy requires a descriptive value) | wikidata-mcp-server/0.1 (https://github.com/cyanheads/wikidata-mcp-server) |
WIKIDATA_SPARQL_TIMEOUT_MS | Max wait for a SPARQL response in ms, retries included; caps every call's timeout (at most 55000) | 55000 |
WIKIDATA_REST_TIMEOUT_MS | Max wait for REST API responses in ms | 10000 |
WIKIDATA_CLAMP_LIMITS | Serve a count above its per-call cap at the cap, with a notice; false rejects it instead | true |
OTEL_ENABLED | Enable OpenTelemetry | false |
See .env.example for the full list of optional overrides.
Running the server
Local development
Requires Bun v1.4.4 or higher (or Node.js ≥24.0.0).
git clone https://github.com/cyanheads/wikidata-mcp-server.git
cd wikidata-mcp-server
bun install
cp .env.example .env
-
Build and run the production version:
# One-time build bun run rebuild # Run the built server bun run start:http # or bun run start:stdio -
Run checks and tests:
bun run devcheck # Lints, formats, type-checks, and more bun run test # Runs the test suite
Docker
docker run --rm -p 3010:3010 ghcr.io/cyanheads/wikidata-mcp-server:latest
The image defaults to HTTP transport, stateless session mode, and logs to /var/log/wikidata-mcp-server. For stdio client configuration, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/wikidata-mcp-server:latest"]. Build locally with docker build -t wikidata-mcp-server .; OpenTelemetry peers are installed by default (--build-arg OTEL_ENABLED=false omits them).
Project structure
| Directory | Purpose |
|---|---|
src/index.ts | createApp() entry point — registers tools and resources, inits services. |
src/mcp-server/tools | Tool definitions (*.tool.ts). Seven tools for entity lookup, statements, sitelinks, SPARQL, and external ID resolution. |
src/mcp-server/resources | Resource definitions. Entity summary resource. |
src/services/wikidata | Wikidata service layer — REST API client, SPARQL client, statement normalization, types. |
src/config | Server-specific environment variable parsing and validation with Zod. |
tests/ | Unit and integration tests, mirroring the src/ structure. |
skills/wikidata-guide/ | Published guide for entity resolution, statements, and SPARQL workflows. |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no
try/catchin tool logic - Use
ctx.logfor logging,ctx.statefor storage - Register new tools and resources in the
createApp()arrays - Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
Contributing
Issues are welcome. Run checks and tests before submitting:
bun run devcheck
bun run test
License
Apache-2.0 — see LICENSE for details.
@cyanheads/wikidata-mcp-servernpm install @cyanheads/wikidata-mcp-server@cyanheads/wikidata-mcp-servernpm install @cyanheads/wikidata-mcp-serverRemote
Related Servers
io.github.cyanheads/anime-mcp-server
Search anime/manga, franchise relations, schedule, characters, rankings, studio filmography.
io.github.cyanheads/art-institute-chicago-mcp-server
Search the Art Institute of Chicago collection: artworks, artists, exhibitions, and audio guides.
io.github.cyanheads/arxiv-mcp-server
Search arXiv, fetch paper metadata, and read full-text content.