io.github.cyanheads/wikidata-mcp-server

Official7 toolsLive

by cyanheads · TypeScript

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

@cyanheads/wikidata-mcp-server (io.github.cyanheads/wikidata-mcp-server)

This MCP server provides tools to search and fetch Wikidata entities, execute SPARQL queries, and resolve external identifiers via Model Context Protocol. It supports communication over STDIO or Streamable HTTP. The repository describes 7 tools and references a resource count of 1.

🛠️ Key Features

Search and fetch Wikidata entities
Execute SPARQL queries
Resolve external identifiers
Transport options: STDIO, Streamable HTTP
Tool count: 7
Resource count: 1

🚀 Use Cases

Querying Wikidata data with SPARQL
Retrieving entities from Wikidata by search
Mapping external identifiers to Wikidata-related entities

⚡ Developer Benefits

Works with MCP for Model Context Protocol integration
Uses Wikidata and SPARQL tooling patterns
Available as a TypeScript-oriented project (repo topics)

⚠️ Limitations

The provided description does not specify authentication, rate limits, or caching behavior.

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.

Parameters5

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

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Search terms to match against entity labels, aliases, and descriptions."
    },
    "type": {
      "default": "item",
      "description": "Entity type to search. Use \"item\" for Q-IDs (people, places, concepts) or \"property\" for P-IDs (predicates).",
      "type": "string",
      "enum": [
        "item",
        "property"
      ]
    },
    "language": {
      "default": "en",
      "description": "BCP 47 language code for returned labels and descriptions (e.g., \"en\", \"de\", \"zh\").",
      "type": "string"
    },
    "limit": {
      "default": 10,
      "description": "Maximum number of results to return. Range: 1–50.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "offset": {
      "default": 0,
      "description": "Pagination offset. Start at 0; increment by limit to page through results.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

wikidata_get_entity

Fetch a Wikidata entity (item or property) by QID or PID. The fields parameter narrows the upstream fetch, not just the response — asking for labels alone costs a fraction of the whole entity, so name the fields you need. Omit fields for all data; a well-connected item is large enough to overflow, and an oversized entity returns kind: "outline" — the field categories with their byte sizes — instead of the data. Follow its retrieval_notice literally rather than picking from sections yourself — it names a fields set already measured to fit, since category sizes are additive and requesting them all would overflow again; for a category too large to deliver whole (statements or sitelinks on a major item) it names the sibling tool that can narrow it. 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, and whenever an entity's statements are large — its properties parameter selects individual P-IDs, granularity fields does not carry.

Parameters3

id	string	required	Q-ID (e.g., "Q76") or P-ID (e.g., "P31"). Case-insensitive — normalized to uppercase.
fields	array	optional	Fields to include. Options: "labels", "descriptions", "aliases", "statements", "sitelinks". Narrows the upstream fetch as well as the response, so a narrow selection is markedly cheaper. Omit for all fields.
languages	array	optional	Language codes to include in labels, descriptions, and aliases (e.g., ["en", "de"]). A requested language with no label of its own falls back to the entity's multilingual ("mul") value, returned under the requested code. Omit to return all available languages.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "Q-ID (e.g., \"Q76\") or P-ID (e.g., \"P31\"). Case-insensitive — normalized to uppercase."
    },
    "fields": {
      "description": "Fields to include. Options: \"labels\", \"descriptions\", \"aliases\", \"statements\", \"sitelinks\". Narrows the upstream fetch as well as the response, so a narrow selection is markedly cheaper. Omit for all fields.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "labels",
          "descriptions",
          "aliases",
          "statements",
          "sitelinks"
        ]
      }
    },
    "languages": {
      "description": "Language codes to include in labels, descriptions, and aliases (e.g., [\"en\", \"de\"]). A requested language with no label of its own falls back to the entity's multilingual (\"mul\") value, returned under the requested code. Omit to return all available languages.",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

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.

Parameters2

ids	array	required	Q-IDs (e.g., "Q76") or P-IDs (e.g., "P31") to resolve. 1–50 IDs per call.
languages	array	optional	BCP 47 language codes for returned labels and descriptions (e.g., ["en", "de", "fr"]). A language with no label of its own falls back to the entity's multilingual ("mul") value, returned under the requested code.

Raw schema

{
  "type": "object",
  "properties": {
    "ids": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Q-IDs (e.g., \"Q76\") or P-IDs (e.g., \"P31\") to resolve. 1–50 IDs per call."
    },
    "languages": {
      "default": [
        "en"
      ],
      "description": "BCP 47 language codes for returned labels and descriptions (e.g., [\"en\", \"de\", \"fr\"]). A language with no label of its own falls back to the entity's multilingual (\"mul\") value, returned under the requested code.",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    }
  },
  "required": [
    "ids"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

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 every statement, and a well-connected item (a country, a major city) carries hundreds of properties: more than fits inline. An oversized set comes back as kind: "outline" — every available P-ID with its byte size, largest first — instead of the statements; re-call with the same id plus properties:[...] naming the P-IDs you want. Designed for fact verification: "what does Wikidata say about this entity's {property}?". Preferred-rank statements are the most current values.

Parameters4

id	string	required	Q-ID (e.g., "Q76") or P-ID of the entity to fetch statements for.
properties	array	optional	P-IDs to fetch (e.g., ["P31", "P569", "P27"]). Omit to return all properties (may be large for major items).
language	string	optional	Language code for label resolution of QID values (e.g., "en", "de").
resolve_labels	boolean	optional	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).

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "Q-ID (e.g., \"Q76\") or P-ID of the entity to fetch statements for."
    },
    "properties": {
      "description": "P-IDs to fetch (e.g., [\"P31\", \"P569\", \"P27\"]). Omit to return all properties (may be large for major items).",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "language": {
      "default": "en",
      "description": "Language code for label resolution of QID values (e.g., \"en\", \"de\").",
      "type": "string"
    },
    "resolve_labels": {
      "default": true,
      "description": "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).",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

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.

Parameters3

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

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "Q-ID of the item (e.g., \"Q76\"). Only items have sitelinks; properties (P-IDs) are not supported."
    },
    "sites": {
      "description": "Optional filter to specific site codes (e.g., [\"enwiki\", \"frwiki\", \"dewiki\"]). Omit to return all sitelinks.",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "wikis_only": {
      "default": false,
      "description": "When true, return only Wikipedia sitelinks (site codes ending in \"wiki\", e.g., \"enwiki\", \"dewiki\"). Excludes Wikisource, Wiktionary, Wikiquote, etc.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

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.

Parameters3

query	string	required	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
language	string	optional	Language for the wikibase:label SERVICE (e.g., "en", "de"). Controls the language of ?<var>Label variables. Set to "" to suppress label SERVICE injection.
timeout	integer	optional	Client-side timeout in seconds (1–55). Capped at 55s — the Wikidata server hard limit is 60s.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "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"
    },
    "language": {
      "default": "en",
      "description": "Language for the wikibase:label SERVICE (e.g., \"en\", \"de\"). Controls the language of ?<var>Label variables. Set to \"\" to suppress label SERVICE injection.",
      "type": "string"
    },
    "timeout": {
      "default": 30,
      "description": "Client-side timeout in seconds (1–55). Capped at 55s — the Wikidata server hard limit is 60s.",
      "type": "integer",
      "minimum": 1,
      "maximum": 55
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

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). The property must be one whose Wikidata data type is external-id — item-valued or media properties (e.g. P31 instance-of, P18 image) are rejected rather than returning an empty match. Known value normalization is applied automatically: surrounding whitespace is trimmed, identifier-resolver URL prefixes are stripped (https://doi.org/, https://pubmed.ncbi.nlm.nih.gov/, https://orcid.org/), DOIs are uppercased, PMID prefixes stripped, ORCID hyphens normalized.

Parameters3

property	string	required	P-ID of the external identifier property, whose Wikidata data type must be external-id (e.g., "P356" for DOI, "P698" for PubMed ID, "P496" for ORCID, "P10283" for OpenAlex ID, "P345" for IMDb ID). Properties of any other data type are rejected — check an unfamiliar P-ID's data type with wikidata_get_entity.
value	string	required	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). A resolver URL is accepted for DOI, PubMed, and ORCID — the prefix is stripped before lookup.
language	string	optional	Language code for label and description in the response (e.g., "en", "de").

Raw schema

{
  "type": "object",
  "properties": {
    "property": {
      "type": "string",
      "minLength": 1,
      "description": "P-ID of the external identifier property, whose Wikidata data type must be external-id (e.g., \"P356\" for DOI, \"P698\" for PubMed ID, \"P496\" for ORCID, \"P10283\" for OpenAlex ID, \"P345\" for IMDb ID). Properties of any other data type are rejected — check an unfamiliar P-ID's data type with wikidata_get_entity."
    },
    "value": {
      "type": "string",
      "minLength": 1,
      "description": "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). A resolver URL is accepted for DOI, PubMed, and ORCID — the prefix is stripped before lookup."
    },
    "language": {
      "default": "en",
      "description": "Language code for label and description in the response (e.g., \"en\", \"de\").",
      "type": "string"
    }
  },
  "required": [
    "property",
    "value"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md15 KBView on GitHub

@cyanheads/wikidata-mcp-server

Search and fetch Wikidata entities, execute SPARQL queries, and resolve external identifiers via MCP. STDIO or Streamable HTTP.

7 Tools • 1 Resource

MCP SDK TypeScript

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

Overview

Wikidata's knowledge graph — entity search and lookup over the REST API v1, graph traversal via SPARQL against the Query Service, batch label resolution through MediaWiki, and external identifier resolution (DOI, PMID, ORCID, OpenAlex, IMDb). Search, fetch, and traverse entities from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

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 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.)

Resources

Resource	Description
`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.

Capability reference

`wikidata_search_entities` _tool

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` _tool

Q-IDs (e.g. Q76) fetch items; P-IDs (e.g. P31) fetch properties — endpoint routing is automatic
fields parameter selects labels, descriptions, aliases, statements, or sitelinks
fields narrows the upstream fetch, not just the response — Q76 is 344,114 bytes whole, 6,703 for labels alone
languages parameter filters multilingual maps to specific language codes, client-side (the entity endpoint takes no language parameter)
An entity too large to inline returns a field-category outline with byte sizes instead of the data — follow its retrieval_notice: it names a literal fields set already measured to fit (category sizes are additive, so requesting every name listed would overflow again), defers the remainder to a further call, and redirects a category too large to deliver whole (statements or sitelinks on a major item) to the tool that can narrow it

`wikidata_get_labels` _tool

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` _tool

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)
A statement set too large to inline returns an outline of the available P-IDs with byte sizes, largest first, instead of the statements — re-call with properties for the ones you need (unfiltered, Q30 carries 467 properties across 1,717 statements)
Preferred-rank statements represent the most current values
Designed for fact verification: "what does Wikidata say about this entity's {property}?"

`wikidata_get_sitelinks` _tool

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` _tool

Full graph power over the Wikidata Query Service (Blazegraph): 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` _tool

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: surrounding whitespace trimmed, resolver URL prefixes stripped (https://doi.org/, https://pubmed.ncbi.nlm.nih.gov/, https://orcid.org/), DOIs uppercased, PMID prefixes stripped, ORCID hyphens normalized
The property's data type must be external-id — item-valued or media properties (e.g. P31, P18) are rejected rather than returning an empty match
Returns match=null when not found (the Query Service lags the live wiki, so a null is not proof of absence)
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

`wikidata://entity/{id}` _resource

Compact markdown summary — labels (all languages), English description, instance-of (P31), enwiki Wikipedia link, image (P18), and statement count
Returned as text/markdown; for full entity data, use wikidata_get_entity
id is 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 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 (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_labels designed to follow SPARQL result sets — run the query, then humanize in one call
wikidata_resolve_external_id returns multipleMatches instead 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 a retrieval_notice naming the exact re-call — instead of a truncated or oversized response

Getting started

Public Hosted Instance

A public instance is available at https://wikidata.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "wikidata-mcp-server": {
      "type": "streamable-http",
      "url": "https://wikidata.caseyjhand.com/mcp"
    }
  }
}

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.4.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

Configure environment:

cp .env.example .env
# edit .env and set any overrides

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`. The framework's `auto` default resolves to `stateful`; this server explicitly selects `stateless`.	`stateless`
`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`

See .env.example for the full list of optional overrides.

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

Docker

docker build -t wikidata-mcp-server .
docker run --rm -p 3010:3010 wikidata-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/wikidata-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit 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.

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
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.

Install

Tools (7)

wikidata_search_entitieswikidata_get_entitywikidata_get_labelswikidata_get_statementswikidata_get_sitelinkswikidata_sparql_querywikidata_resolve_external_id

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'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "wikidata-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/wikidata-mcp-server@0.1.19",
        "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"
      }
    }
  }
}

@cyanheads/wikidata-mcp-server (io.github.cyanheads/wikidata-mcp-server)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

wikidata_search_entities

wikidata_get_entity

wikidata_get_labels

wikidata_get_statements

wikidata_get_sitelinks

wikidata_sparql_query

wikidata_resolve_external_id

@cyanheads/wikidata-mcp-server

Overview

Tools

Resources

Capability reference

wikidata_search_entities tool

wikidata_get_entity tool

wikidata_get_labels tool

wikidata_get_statements tool

wikidata_get_sitelinks tool

wikidata_sparql_query tool

wikidata_resolve_external_id tool

wikidata://entity/{id} resource

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`wikidata_search_entities` _tool

`wikidata_get_entity` _tool

`wikidata_get_labels` _tool

`wikidata_get_statements` _tool

`wikidata_get_sitelinks` _tool

`wikidata_sparql_query` _tool

`wikidata_resolve_external_id` _tool

`wikidata://entity/{id}` _resource