Wikidata Mcp Server

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

Resources

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 (Wikidata language codes such as en, de, pt-br; case-insensitive)
• 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; every returned language is rendered
• 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
• Item QIDs and quantity units are resolved to human-readable labels by default — in main values, qualifiers, and references — via one batched label call
• References stay grouped by source, and unknown or explicitly absent values come back as somevalue / novalue
• 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, measured before any label lookup is made — re-call with properties naming P-IDs whose sizes sum to 24,000 or less (the retrieval_notice names one such set); labels are added after that check (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 the query uses a ?<var>Label, ?<var>Description, or ?<var>AltLabel variable and declares no label SERVICE of its own
• language takes one code or a comma-separated fallback list (fr,en); labels fall back to the multilingual (mul) label last
• SELECT queries only — ASK, CONSTRUCT, DESCRIBE, updates, and plain search text are rejected before the request is sent
• Results in SPARQL 1.1 JSON format: each binding is { type, value, "xml:lang"?, datatype? }; the rendered table quotes literals with their @lang or ^^datatype and shows URIs as prefixed names or <…>
• Each response is held to 64,000 bytes, cut between whole rows: a larger result returns its leading rows on both surfaces with returnedCount, totalCount, and a notice to page with ORDER BY plus LIMIT/OFFSET or aggregate in the query
• 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)
• The label comes in the requested language, falling back to the entity's multilingual (mul) label
• 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:

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

{
  "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):

{
  "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:

{
  "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

1. Clone the repository:

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

2. Navigate into the directory:

cd wikidata-mcp-server

3. Install dependencies:

bun install

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

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

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.