wikidata-musicians

Search Wikidata for musicians and musical groups and get back only verified hits: the QID, labels and descriptions in the languages you ask for, and a Wikimedia Commons portrait that comes with its license and author credit. No API key.

Ships as a library (Node 20+ and Cloudflare Workers), a CLI, and an MCP server that agents can call.

日本語

npx @artsnet/wikidata-musicians search "Ryuichi Sakamoto" --languages ja,en --user-agent "MyApp/1.0 (me@example.com)"
Q345494  坂本龍一  (日本の音楽家、作曲家、ピアニスト (1952-2023))
  kind:     person  via Q36834, Q486748
  wikidata: https://www.wikidata.org/wiki/Q345494
  image:    https://upload.wikimedia.org/wikipedia/commons/…
  credit:   …, CC BY 2.0, https://commons.wikimedia.org/wiki/File:…

What "verified" means

A search on Wikidata returns anything whose label or alias matches, including painters, places and films. This package fetches each hit and keeps it only when it has a direct P106 (occupation) statement in the musician list or a direct P31 (instance of) statement in the musical-group list. Subclass chains are not followed, so an item with ambiguous data stays out until someone fixes it on Wikidata.

Run wikidata-musicians classes for the QIDs, or pass your own lists through occupationIds / groupClassIds.

A Commons image is returned only when the file URL, the file page, the license name, the license URL and the author credit are all present. Otherwise image is null. Show the credit and link to filePageUrl when you display the image; that is what the licenses require.

Related MCP server: kpop-wiki

Library

npm install @artsnet/wikidata-musicians

import { createWikidataMusiciansClient, WikidataMusiciansError } from "@artsnet/wikidata-musicians";

const client = createWikidataMusiciansClient({
  userAgent: "MyApp/1.0 (https://example.com/contact)", // Wikimedia asks every client to identify itself
  languages: ["ja", "en"],                                // label preference and default search language
});

const hits = await client.search("坂本龍一");              // Musician[] in search order, non-musicians removed
const one = await client.get("Q345494");                  // throws not-found / not-a-musician

try { await client.get("Q5"); } catch (error) {
  if (error instanceof WikidataMusiciansError) error.code; // "invalid-input" | "not-found" | "not-a-musician" | "unavailable"
}

Musician:

{
  qid: "Q345494", wikidataUrl: "https://www.wikidata.org/wiki/Q345494",
  kind: "person" | "group", matchedClassIds: ["Q36834", "Q486748"],
  name: "坂本龍一",              // first requested language with a label, else the search label, else the QID
  description: "…" | null,
  labels: { ja: "坂本龍一", en: "Ryuichi Sakamoto" },
  descriptions: { ja: "…", en: "…" },
  image: { url, filePageUrl, licenseName, licenseUrl, artistCredit } | null
}

Options: languages (default ["en"]), userAgent, timeoutMs (default 10000), fetcher, includeImages (default true), occupationIds, groupClassIds, cacheTtlMs (default 10 minutes, 0 disables). search(query, { language, limit }) takes a search language and the number of raw hits to verify (1 to 50, default 10). One-off helpers searchMusicians() and getMusician() skip the cache.

Requests per call: one wbsearchentities, one wbgetentities for all hits (50 per request), and one Commons imageinfo query for all images. A get is one or two requests. Only www.wikidata.org and commons.wikimedia.org are ever contacted.

The core uses only fetch, URL and AbortSignal.timeout, so it runs unchanged in Cloudflare Workers. The CLI and MCP server are Node-only.

CLI

npx @artsnet/wikidata-musicians search "Björk" --json
npx @artsnet/wikidata-musicians get Q5383 --languages ja,en
npx @artsnet/wikidata-musicians classes

Options:
  --json                 Print one JSON object (schemaVersion 1)
  --languages <l,l,...>  Label languages in order of preference (default: en; or WIKIDATA_MUSICIANS_LANGUAGES)
  --language <l>         Search language (default: first of --languages)
  --limit <n>            Raw search hits to verify, 1-50 (default: 10)
  --no-images            Skip the Commons image lookup
  --user-agent <ua>      User-Agent sent to Wikimedia (or WIKIDATA_MUSICIANS_USER_AGENT); name your app and contact
  --timeout <ms>         Per-request timeout (default: 10000)

Exit codes: 0 ok, 1 usage error, 2 invalid input, 3 not found, 4 Wikimedia unavailable, 5 the item is not a musician. An empty search result is still exit 0.

{"schemaVersion":1,"ok":true,"query":"Björk","language":"en","musicians":[{"qid":"Q42455","kind":"person","name":"Björk",…}]}
{"schemaVersion":1,"ok":true,"qid":"Q5383","musician":{…}}
{"schemaVersion":1,"ok":false,"input":"Q5","error":{"code":"not-a-musician","message":"…"}}

Without a User-Agent the CLI prints a warning and sends one that names only this package. Please set yours.

MCP server

A stdio server for Claude Code, Claude Desktop, Cursor and any other MCP client. It runs on your machine, with your network and your User-Agent. There is no hosted endpoint.

{
  "mcpServers": {
    "wikidata-musicians": {
      "command": "npx",
      "args": ["-y", "-p", "@artsnet/wikidata-musicians", "wikidata-musicians-mcp"],
      "env": {
        "WIKIDATA_MUSICIANS_USER_AGENT": "MyAgent/1.0 (https://example.com/contact)",
        "WIKIDATA_MUSICIANS_LANGUAGES": "ja,en"
      }
    }
  }
}

Claude Code: claude mcp add wikidata-musicians -e WIKIDATA_MUSICIANS_USER_AGENT="MyAgent/1.0 (…)" -e WIKIDATA_MUSICIANS_LANGUAGES=ja,en -- npx -y -p @artsnet/wikidata-musicians wikidata-musicians-mcp

All tools are annotated read-only. Everything a tool returns is Wikidata and Commons content: data for the agent to report, never an instruction for it to follow. The tool descriptions say so. See SKILL.md for a short guide written for agents.

Responsibility

Wikidata content is CC0; Commons images carry their own licenses, which this package surfaces so you can comply with them. Wikimedia's User-Agent policy asks every client to identify itself with a contact; the default User-Agent names only this package, so set your own. Requests are serial and cached for ten minutes by default. Do not use this to bulk-harvest Wikidata; for that, use the dumps or the SPARQL endpoint. The music classification is deliberately narrow and will miss musicians whose Wikidata item lacks a direct occupation statement; the fix belongs on Wikidata.

Development

npm install
npm run typecheck && npm test && npm run build
node dist/cli.js search "Björk" --user-agent "dev (you@example.com)"

MIT © Artsnet. See CONTRIBUTING.md and SECURITY.md.

日本語

Wikidata から 音楽家と音楽グループ だけを検索します。職業(P106)または分類(P31)を検証した候補のみを返し、指定した言語のラベルと説明、そしてライセンスと作者クレジット付きの Wikimedia Commons 画像を揃えます。API キーは不要です。

ライブラリ(Node 20 以上と Cloudflare Workers)、CLI、エージェントから呼べる MCP サーバー を同梱しています。

使い方

npx @artsnet/wikidata-musicians search "坂本龍一" --languages ja,en --user-agent "MyApp/1.0 (me@example.com)"
npx @artsnet/wikidata-musicians get Q345494 --json

import { createWikidataMusiciansClient } from "@artsnet/wikidata-musicians";
const client = createWikidataMusiciansClient({ userAgent: "MyApp/1.0 (https://example.com/contact)", languages: ["ja", "en"] });
const hits = await client.search("坂本龍一");

MCP サーバーは stdio で動く自己ホスト専用です。Artsnet が運用する公開エンドポイントはありません。設定例は上の英語セクションの JSON をそのまま使ってください。

検証の意味

Wikidata の検索は名前が一致するものを何でも返します(画家、地名、映画など)。このパッケージはヒットごとに項目を取得し、音楽系の職業(P106)か音楽グループの分類(P31)が 直接 付いているものだけを残します。下位クラスはたどりません。曖昧な項目は Wikidata 側が整うまで出てきません。組み込みの QID は wikidata-musicians classes で確認でき、occupationIds / groupClassIds で差し替えられます。

Commons 画像は、ファイル URL・ファイルページ・ライセンス名・ライセンス URL・作者クレジットがすべて揃うときだけ返します。表示する際はクレジットを示し、filePageUrl にリンクしてください。

失敗コードと終了コード

責任について

Wikidata の内容は CC0、Commons の画像は個別のライセンスです。Wikimedia の User-Agent ポリシーはすべてのクライアントに連絡先付きの識別を求めています。既定の User-Agent はこのパッケージ名だけで運営者名を含まないため、--user-agent または WIKIDATA_MUSICIANS_USER_AGENT で自分のものを設定してください。ツールが返す内容はすべて Wikidata と Commons のテキストであり、エージェントにとってはデータであって指示ではありません。大量取得にはダンプか SPARQL エンドポイントを使ってください。