io.github.cyanheads/wikidata-mcp-server

Official7 tools

by cyanheads · TypeScript

Search and fetch Wikidata entities, execute SPARQL queries, and resolve external identifiers.

Query Wikidata entities and execute SPARQL queries to retrieve structured knowledge.

Topics

bunknowledge-graphlinked-datamcpmcp-servermodel-context-protocolsparqltypescriptwikibasewikidataai-agentcyanheads

Captured live from the server via tools/list.

wikidata_search_entities

Search Wikidata for items or properties by text query. Returns QIDs or PIDs with labels, descriptions, and match metadata indicating whether the hit was on a label or alias. Use type="item" for real-world concepts (people, places, works) and type="property" to find predicate P-IDs. The API returns no total count — pagination is offset-based with no result ceiling indicator.

Parameters (5)

querystringrequired
Search terms to match against entity labels, aliases, and descriptions.
typestring
Entity type to search. Use "item" for Q-IDs (people, places, concepts) or "property" for P-IDs (predicates).
languagestring
BCP 47 language code for returned labels and descriptions (e.g., "en", "de", "zh").
limitinteger
Maximum number of results to return. Range: 1–50.
offsetinteger
Pagination offset. Start at 0; increment by limit to page through results.

wikidata_get_entity

Fetch a Wikidata entity (item or property) by QID or PID. Use the fields parameter to trim what is returned to the caller — major items can be large. Omit fields to get all data. Q-IDs (e.g. Q76) fetch items; P-IDs (e.g. P31) fetch properties from the correct endpoint automatically. Use wikidata_get_statements for deep claim traversal with label resolution.

Parameters (3)

idstringrequired
Q-ID (e.g., "Q76") or P-ID (e.g., "P31"). Case-insensitive — normalized to uppercase.
fieldsarray
Fields to include in the response. Options: "labels", "descriptions", "aliases", "statements", "sitelinks". Omit for all fields.
languagesarray
Language codes to include in labels, descriptions, and aliases (e.g., ["en", "de"]). Omit to return all available languages.

wikidata_get_labels

Resolve one or more QIDs or PIDs to their human-readable labels and descriptions. Lightweight — returns no claim data. Supports up to 50 IDs per call (batched automatically). Designed for the common agent pattern: receive QIDs from a SPARQL query, then humanize them.

Parameters (2)

idsarrayrequired
Q-IDs (e.g., "Q76") or P-IDs (e.g., "P31") to resolve. 1–50 IDs per call.
languagesarray
BCP 47 language codes for returned labels and descriptions (e.g., ["en", "de", "fr"]).

wikidata_get_statements

Fetch property claims for a Wikidata entity with qualifier and reference detail. Value QIDs are resolved to human-readable labels by default. Use the properties parameter to fetch only specific P-IDs — omitting it returns all statements, which can be large. Designed for fact verification: "what does Wikidata say about this entity's {property}?". Preferred-rank statements are the most current values.

Parameters (4)

idstringrequired
Q-ID (e.g., "Q76") or P-ID of the entity to fetch statements for.
propertiesarray
P-IDs to fetch (e.g., ["P31", "P569", "P27"]). Omit to return all properties (may be large for major items).
languagestring
Language code for label resolution of QID values (e.g., "en", "de").
resolve_labelsboolean
Resolve wikibase-item value QIDs to human-readable labels via a batched label call. Set to false to skip label resolution and return raw QIDs only (faster, smaller payload).

wikidata_get_sitelinks

Fetch Wikipedia and Wikimedia project article URLs for a Wikidata item. A sitelink maps a site code (e.g., "enwiki") to a Wikipedia article title and URL. Major items can have 300+ sitelinks across languages. Use sites to filter to specific language editions, or wikis_only to return only Wikipedia links. Only Q-IDs (items) have sitelinks — properties (P-IDs) do not.

Parameters (3)

idstringrequired
Q-ID of the item (e.g., "Q76"). Only items have sitelinks; properties (P-IDs) are not supported.
sitesarray
Optional filter to specific site codes (e.g., ["enwiki", "frwiki", "dewiki"]). Omit to return all sitelinks.
wikis_onlyboolean
When true, return only Wikipedia sitelinks (site codes ending in "wiki", e.g., "enwiki", "dewiki"). Excludes Wikisource, Wiktionary, Wikiquote, etc.

wikidata_sparql_query

Execute a SPARQL SELECT query against the Wikidata Query Service. Full graph power: multi-hop traversals, aggregations, subqueries, OPTIONAL, FILTER, UNION, BIND. Standard Wikidata prefixes (wd:, wdt:, p:, ps:, pq:, wikibase:, bd:) are auto-injected. The wikibase:label SERVICE is also auto-injected when language is set and the query includes ?<var>Label variables — so you can use ?itemLabel without writing the boilerplate. Hard server timeout is 60s; use LIMIT to keep queries fast. Bindings use the SPARQL 1.1 JSON format: each value is { type, value, "xml:lang"? }. Use wikidata_get_labels to humanize QID results from this tool.

Parameters (3)

querystringrequired
SPARQL SELECT query. Must be a SELECT query (not CONSTRUCT/DESCRIBE/ASK). Standard prefixes (wd:, wdt:, p:, ps:, pq:, wikibase:, bd:) are injected automatically. Example: SELECT ?item ?itemLabel WHERE { ?item wdt:P31 wd:Q146. } LIMIT 10
languagestring
Language for the wikibase:label SERVICE (e.g., "en", "de"). Controls the language of ?<var>Label variables. Set to "" to suppress label SERVICE injection.
timeoutinteger
Client-side timeout in seconds (1–55). Capped at 55s — the Wikidata server hard limit is 60s.

wikidata_resolve_external_id

Look up a Wikidata entity by an external identifier such as a DOI, PubMed ID, ORCID iD, or OpenAlex ID. Returns match=<entity> on success, match=null when not found, and match=null with multipleMatches populated when a Wikidata data integrity issue causes more than one entity to claim the same external ID. Common cross-server join use cases: CrossRef DOI → Wikidata paper QID (P356), PubMed PMID → Wikidata paper QID (P698), ORCID → author QID (P496), OpenAlex ID → entity QID (P10283). Known value normalization is applied automatically: DOIs are uppercased, PMID prefixes stripped, ORCID hyphens normalized.

Parameters (3)

propertystringrequired
P-ID of the external identifier property (e.g., "P356" for DOI, "P698" for PubMed ID, "P496" for ORCID, "P10283" for OpenAlex ID, "P345" for IMDb ID).
valuestringrequired
The external identifier value to look up (e.g., "10.1038/nature01234" for a DOI, "32283226" for a PubMed ID, "0000-0002-1825-0097" for an ORCID).
languagestring
Language code for label and description in the response (e.g., "en", "de").

README.md12 KBView on GitHub

<div align="center"> <h1>@cyanheads/wikidata-mcp-server</h1> <p><b>Search and fetch Wikidata entities, execute SPARQL queries, and resolve external identifiers via MCP. STDIO or Streamable HTTP.</b> <div>7 Tools • 1 Resource</div> </p> </div> <div align="center">

</div> <div align="center">

Public Hosted Server: https://wikidata.caseyjhand.com/mcp

</div>

Tools

7 tools for working with Wikidata's knowledge graph:

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 50 QIDs or PIDs to human-readable labels and descriptions
`wikidata_get_statements`	Fetch property claims for an entity with qualifier detail and QID 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.)

`wikidata_search_entities`

Search Wikidata for items or properties by text query.

Searches labels, aliases, and descriptions
type="item" for real-world concepts (people, places, works); type="property" for predicate P-IDs
Language-aware results (BCP 47 language codes)
Offset-based pagination, up to 50 results per call
Returns match metadata indicating whether the hit was on a label or alias

`wikidata_get_entity`

Fetch a Wikidata entity by QID or PID with field selection.

Q-IDs (e.g. Q76) fetch items; P-IDs (e.g. P31) fetch properties — endpoint routing is automatic
fields parameter trims the response to labels, descriptions, aliases, statements, or sitelinks
languages parameter filters multilingual maps to specific language codes
Full entity payload always fetched from the API; field/language filtering is client-side

`wikidata_get_labels`

Batch-resolve QIDs/PIDs to human-readable labels and descriptions.

Up to 50 IDs per call, batched via the MediaWiki wbgetentities API
Supports multiple language codes per request
Reports found count and notFound IDs for partial-result handling
Designed for the common agent pattern: run a SPARQL query, then humanize the QID results

`wikidata_get_statements`

Fetch property claims for a Wikidata entity with full qualifier and reference detail.

properties parameter fetches only specific P-IDs — omit to return all statements
Value QIDs are resolved to human-readable labels by default via a batched label call
Set resolve_labels=false for raw QIDs only (faster, smaller payload)
Preferred-rank statements represent the most current values
Designed for fact verification: "what does Wikidata say about this entity's {property}?"

`wikidata_get_sitelinks`

Fetch Wikipedia and Wikimedia project article URLs for a Wikidata item.

Maps site codes (e.g., enwiki) to article titles and URLs
sites parameter filters to specific site codes
wikis_only=true returns only Wikipedia links (excludes Wiktionary, Wikiquote, Wikisource, etc.)
Major items can have 300+ sitelinks across languages
Only Q-IDs (items) have sitelinks — P-IDs are not supported

`wikidata_sparql_query`

Execute a SPARQL SELECT query against the Wikidata Query Service (Blazegraph).

Full graph power: multi-hop traversals, aggregations, subqueries, OPTIONAL, FILTER, UNION, BIND
Standard Wikidata prefixes (wd:, wdt:, p:, ps:, pq:, wikibase:, bd:) are auto-injected
wikibase:label SERVICE auto-injected when language is set and the query uses ?<var>Label variables
Results in SPARQL 1.1 JSON format: each binding is { type, value, "xml:lang"? }
Hard server timeout is 60s; client-side timeout parameter (1–55s) applies earlier
Rate-limited at 60 requests/min and 5 concurrent requests per IP

`wikidata_resolve_external_id`

Look up a Wikidata entity by an external identifier.

Common use cases: CrossRef DOI → QID (P356), PubMed PMID → QID (P698), ORCID → author QID (P496), OpenAlex ID → entity QID (P10283), IMDb ID (P345)
Automatic value normalization: DOIs uppercased, PMID prefixes stripped, ORCID hyphens normalized
Returns match=null when not found
Returns multipleMatches when a Wikidata data integrity issue causes more than one entity to claim the same external ID
Designed for cross-server joins with pubmed-mcp-server, crossref-mcp-server, and openalex-mcp-server

Resource

Type	Name	Description
Resource	`wikidata://entity/{id}`	Compact markdown summary of a Wikidata entity — labels, English description, instance-of, Wikipedia link, image, and statement count

All resource data is also reachable via tools.

Features

Built on @cyanheads/mcp-ts-core:

Declarative tool definitions — single file per tool, framework handles registration and validation
Unified error handling across all tools
Pluggable auth (none, jwt, oauth)
Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
Structured logging with optional OpenTelemetry tracing
Runs locally (stdio/HTTP) from the same codebase

Wikidata-specific:

Wikidata REST API v1 for entity and statement fetches — no SPARQL overhead for lookup operations
MediaWiki wbgetentities API for efficient batch label resolution
Wikidata Query Service (Blazegraph) for SPARQL with auto-injected prefix headers and label SERVICE
Configurable User-Agent per Wikimedia policy
Separate timeout configuration for REST and SPARQL endpoints

Agent-friendly output:

wikidata_get_labels designed to follow SPARQL result sets — run the query, then humanize in one call
wikidata_resolve_external_id handles DOI/PMID/ORCID normalization transparently, with multipleMatches for data integrity edge cases
wikidata_get_statements resolves QID values to labels in the same call, with resolve_labels=false escape hatch for raw payloads
All tools echo input parameters in the response for traceability

Getting started

Self-Hosted / Local

Add the following to your MCP client configuration file.

json

{
  "mcpServers": {
    "wikidata-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/wikidata-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "wikidata-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/wikidata-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "wikidata-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/wikidata-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.3.0 or higher (or Node.js ≥ 24.0.0).

Installation

Clone the repository:

git clone https://github.com/cyanheads/wikidata-mcp-server.git

Navigate into the directory:

cd wikidata-mcp-server

Install dependencies:

bun install

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_LOG_LEVEL`	Log level (`debug`, `info`, `notice`, `warning`, `error`)	`info`
`MCP_GC_PRESSURE_INTERVAL_MS`	Opt-in Bun-only forced-GC interval (ms). Try `60000` if heap growth is observed under HTTP load.	`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	`55000`
`WIKIDATA_REST_TIMEOUT_MS`	Max wait for REST API responses in ms	`10000`
`OTEL_ENABLED`	Enable OpenTelemetry	`false`

Running the server

Local development

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

Project structure

Directory	Purpose
`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.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for logging, ctx.state for storage
Register new tools and resources in the createApp() arrays

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Configuration

Environment variables

WIKIDATA_USER_AGENTdefault wikidata-mcp-server/0.1 (https://github.com/cyanheads/wikidata-mcp-server)

User-Agent string for Wikimedia requests. Wikimedia policy requires a descriptive value.

WIKIDATA_SPARQL_TIMEOUT_MSdefault 55000

Max time to wait for a SPARQL response in milliseconds.

WIKIDATA_REST_TIMEOUT_MSdefault 10000

Max time to wait for REST API responses in milliseconds.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

claude_desktop_config.json

{
  "mcpServers": {
    "wikidata-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/wikidata-mcp-server@0.1.14",
        "run",
        "start:stdio"
      ],
      "env": {
        "WIKIDATA_USER_AGENT": "wikidata-mcp-server/0.1 (https://github.com/cyanheads/wikidata-mcp-server)",
        "WIKIDATA_SPARQL_TIMEOUT_MS": "55000",
        "WIKIDATA_REST_TIMEOUT_MS": "10000",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}