@cyanheads/orcid-mcp-server
Search and retrieve researcher profiles, works, affiliations, funding, and peer review records from the ORCID registry via MCP. STDIO or Streamable HTTP.
9 Tools • 2 Resources
Overview
Researcher identity data from the ORCID registry. Search and disambiguate authors, build a researcher dossier from profile, works, affiliations, funding, and peer review records, and chain external identifiers to Crossref, PubMed, or arXiv.
Tools
Resources
All resource data is also reachable via tools. Use resources when injecting stable researcher context into a prompt; use tools when filtering or processing results is needed.
The server also publishes an agent skill, orcid-guide (skill://orcid-guide/SKILL.md, source in skills/orcid-guide/): identity-confirmation gates, identifier chains between the tools, and raw Solr field syntax.
Capability reference
orcid_search_researchers tool
- Structured params —
given_name, family_name, affiliation, keyword, ror_id, doi, pmid, grant_number — AND together automatically; query adds raw Solr syntax — sent as written when it is the only field, otherwise ANDed as one parenthesized group so a top-level OR keeps its alternatives (an exclusion-only query such as -keyword:x is ANDed ungrouped, since ORCID matches nothing for a group of only exclusions)
- At least one param must be non-blank — an empty or whitespace-only search is rejected rather than run against the whole registry
given_name phrase-matches, except that a value of only initials (J., J. A.) matches given names starting with each letter
doi and pmid map to doi-self / pmid-self field queries — finds researchers who linked that specific work to their ORCID record. URL and label forms (https://doi.org/…, doi:…, https://pubmed.ncbi.nlm.nih.gov/…/, PMID:…) are accepted and reduced to the bare identifier. A DOI anchors as one doi-self regex term that matches it in any ASCII letter case, bare or behind http(s)://, dx., doi.org/, or doi: in any case, whichever form the record holds; it stays self-only and exact (no part-of links, no version suffixes). Nonblank values must contain a complete DOI (10. followed by digits, /, and a non-whitespace suffix) or numeric PMID; malformed and prefix-only values fail before a request. Omitted or genuinely blank fields remain unset
ror_id takes a ROR ID bare (00f54p054) or as a ror.org URL (https://ror.org/…, ror.org/…, a www. host, a trailing slash), in either letter case, and is reduced to the https://ror.org/<lowercase id> form ORCID indexes; a value that is not a ROR ID, or whose check digits do not match, is rejected before any search runs
grant_number phrase-matches the grant numbers on researchers' funding items, case-insensitively, over the parts between separators such as hyphens and slashes — 5F31MH010500 also matches 5F31MH010500-03, but a number cut mid-part matches nothing — pair with orcid_get_funding to inspect each match
rows: results per page, default 20; a larger value (up to 10,000) is clamped to 1,000, the most ORCID serves per request, and a notice names both sizes on both surfaces. start: 0–10,000 offset pagination (the ORCID Public API's ceiling for unauthenticated requests)
- A page returns
rows results, fewer only at the end of the matches; nextStart is start plus the number returned while matches remain
- Returns expanded-search results with inline name and institution data — no follow-up profile fetch needed for basic discovery
- Use for precise field-anchored lookups; use
orcid_resolve_researcher for ambiguous names needing ranked disambiguation
orcid_get_profile tool
- Accepts a bare ORCID iD (
0000-0001-2345-6789) or an orcid.org URI (https://orcid.org/…, orcid.org/…, a www. host, a trailing slash); a lowercase x check digit is canonicalized to X. Every tool that takes orcid_id accepts the same forms; the orcid://researcher/{orcid_id}/… resources take the bare iD
- A deprecated iD — one ORCID merged into another account — resolves to the primary record on every record tool and both resources, and
orcidId/orcidUri report the primary iD; on the tools, selfAsserted is judged against it and a notice names both iDs. The three endpoints ORCID does not redirect are resolved through a /person merge check; when that check cannot run, the answer says its result is unconfirmed and to call again
- Returns name, other names (former names, transliterations, initialed forms), biography, keywords, researcher URLs, external identifiers (Scopus Author ID, ResearcherID, Loop, etc.), emails, and country codes — all in one response
- Each email carries
verified as ORCID publishes it (shown in the text as (verified) / (unverified)); ORCID exposes only verified addresses publicly, so it reads true in practice
include_history (default false) reads the full /record in place of /person, still one request, and adds history: createdDate, creationMethod (API, DIRECT, MEMBER_REFERRED, WEBSITE), claimed, verifiedEmail (private addresses included), verifiedPrimaryEmail, and lastModifiedDate, each only when ORCID published it. These are the record's trust signals. The upstream response can exceed 10 MB for a heavy publisher, and the first call for such a record can time out while ORCID builds it (call again); the activities summary is never parsed and the tool output stays small
- Only publicly visible fields are returned; researchers control per-field visibility. A
notice names every section with no public data (e.g. "no public email addresses or countries"), since an empty section can be private rather than empty
- Entry point for building a researcher dossier before fetching works or affiliations
orcid_get_works tool
work_types keeps works of the listed types (ORCID's 58-value vocabulary, e.g. journal-article, preprint, data-set; any listed type matches, an empty list filters nothing); year_from and year_to keep works published in that inclusive range, read from the first four digits of publicationDate. Under a year bound, undated works drop out and a notice counts them. The filters run over the whole record before paging, at no extra upstream cost: matchedCount counts the matches, workCount the whole record, and appliedFilters echoes what was applied
- Returns 25 matching works by default;
limit is clamped to 1,000 (accepted up to 10,000) with a notice naming both sizes. Page with offset and the returned nextOffset; a page holds limit works, fewer only at the end, and truncated says more remain. An offset past the matches returns a notice saying so; no match returns a notice naming the filters and workCount
- Set
include_external_ids to false to drop DOI/PMID/arXiv/ISBN identifier lists for a lighter payload
- One record per ORCID work group; its identifiers are the group's — the preferred version's own, then any that another source holds, such as a PMID beside a Crossref DOI
- External identifiers are pre-formatted for chaining to Crossref, PubMed, or arXiv
- Summaries only — pass a work's
putCode to orcid_get_work_detail for abstracts and contributor lists
- Each work lists its
sources — the researcher, or member organizations such as Crossref or a university system — with selfAsserted marking what the researcher asserted; an empty list does not mean no publications
orcid_get_work_detail tool
put_codes: 1–1,000 raw codes per call (from orcid_get_works), deduplicated in first-occurrence order before fetching the first 100 distinct codes in one request; every record ORCID returns for them comes back, and a notice names the input cap when applied
- Returns abstract, contributors with CRediT roles, the record's external IDs, citation metadata (BibTeX or other deposited formats), journal title, and URL
- A record listing more than 100 contributors keeps the first 100 plus the researcher's own entries, matched by ORCID iD, with
contributorCount and contributorsTruncated marking the cut; a citation over 8,192 bytes is left out and flagged citationOmitted, so a large-collaboration paper costs about what its other fields do. Even so, 100 large-collaboration records run past 1 MB: size batches to what the step needs
- Each put-code is one source's version of the work, so its identifiers can be fewer than
orcid_get_works lists for the work group; sources names that source
- Per-put-code failures (not found or inaccessible) arrive as
errors entries — the rest of the batch still resolves
deferredPutCodes lists, in request order, the distinct codes beyond the input cap and any ORCID's answer left out; pass it as put_codes in another call. Notices distinguish the two causes
- An upstream rate limit surfaces as a
RateLimited error carrying ORCID's retryAfter when it sent one
orcid_get_affiliations tool
types filters which sections to return: employment, education, invited-positions, distinctions, memberships, qualifications, services, or all — default is employment + education; an explicit empty list is rejected
- One upstream call regardless of how many types are requested
- Returns organization name, disambiguated ID (ROR/GRID/Ringgold), department, role, and date range per record
- Each record's
sources names who added it — the researcher, or a member organization such as a university research information system; an empty result does not mean no affiliation
orcid_get_funding tool
- Without
put_code, returns the complete grouped funding list in one request with view: summary; each preferred summary exposes its optional putCode
- Returns funding type (grant, contract, award, salary-award), funder name and disambiguated ID (Crossref Funder ID/ROR), grant numbers, and funding period
- One record per ORCID funding group, from its preferred version — a grant deposited twice counts once in
fundingCount; when the group's versions record distinct award periods, such as renewals under one grant number, periods lists each
- Supply a summary
putCode as put_code for view: detail: fetches only that deposit, with its own source and optional description, URL, amount: { value?, currency? }, organizationDefinedType (the deposit's funding subtype, free text, present only when deposited), and contributors (name?, orcidId?, role?: lead, co-lead, supported-by, or other-contribution). Decimal text is preserved exactly; missing amounts and currencies stay absent
contributors is always present in detail ([] when none was deposited, which is not evidence the researcher had no role), in upstream order and whole, and never in summary
- The deposited description arrives whole (ORCID caps it at 5,000 characters); the text surface represents it as a JSON string so original CRLF line endings survive
- An unavailable selected deposit returns
funding_not_found and denied public access returns funding_inaccessible; each error explains how to recover
- Funding comes from the researcher or from member organizations (funders, institutions, search-and-link tools), and each record's
sources names which; most researchers with real grants have no entries here, and absence does not imply no funding
orcid_get_peer_reviews tool
- Pages the history in upstream order with
offset (default 0) and limit (default 25; a larger value, up to 10,000, is clamped to 1,000 with a notice naming both sizes on both surfaces)
reviewCount counts returned reviews, limit of them, fewer only at the end; totalCount reports the full history. Continue with nextOffset when truncated is true. Empty and past-end pages retain the total with no continuation, and an offset past a non-empty history returns a notice saying so
- Returns reviewer role (
reviewer, editor, chair, etc.), review type, completion date, an ISSN-keyed group identifier, and the convening organization ORCID records per record
- The convening organization is often the service that imported the review (Publons, Clarivate) rather than the journal; ORCID returns no journal name, so the ISSN is the journal key and heads each review that has one
- Reviews come from the researcher or from member organizations that import them, and each record's
sources names which; coverage varies widely by researcher
orcid_get_research_resources tool
- Covers compute allocations, equipment access, lab facilities, data resources, and clinical study registrations
- A newer, sparsely populated ORCID section — most researchers have zero entries, and absence does not imply none exist
- Entries are typically deposited by resource-allocation systems (e.g. ACCESS, XSEDE) rather than added by the researcher
- Returns resource title, hosting organization (with disambiguated ID), external identifiers (often a portal URI), access period, and the
sources that deposited it
- Default
view: summary lists proposals; proposalHosts includes every proposal host, while hostOrganization keeps the first host for compatibility
- Supply a proposal's
putCode as put_code for view: detail: each item carries its name, type, all operators in hosts, external identifiers, and URL; proposal provenance stays on the resource record
- Detail pages return
item_limit items from item_offset: item_offset defaults to 0, item_limit to 25, and a larger item_limit returns at most 100 (accepted maximum 10,000); both require put_code. itemCount, returnedItemCount, itemOffset, itemsTruncated, and nextItemOffset describe the page; top-level truncated mirrors itemsTruncated, and itemLimitNotice discloses a reduced limit on both surfaces
- Each page repeats the proposal metadata; resume at
nextItemOffset with the same put_code. Empty and past-end pages have no continuation
orcid_resolve_researcher tool
- Returns ranked candidates (
rows default 5; a larger value, up to 10,000, returns at most 20 at every search stage) with transparent disambiguation signals: name match type (exact/partial/other-name/none), institution overlap flag, and anchor type (doi/pmid/none). Each candidate carries otherNames, the other names on its ORCID record, verbatim
- One
notice joins, in order: the requested and effective sizes when capped; that the candidates were found by the DOI or PMID alone because no record matched the name with the anchors supplied (it names every anchor you gave); and, when totalFound exceeds the candidates ranked, The ranking covers N of T records matching queryUsed, with the rows value to call again with (up to 20) and, past 20, how to list the rest: orcid_search_researchers with query set to queryUsed and start set to N, which returns them in ORCID's relevance order without match signals. With no candidates it carries the empty-result guidance instead. The notice is plain text in structuredContent and escaped only in content[]
- Name and institution comparisons are case- and accent-insensitive —
José Baselga and Jose Baselga classify the same candidate identically — and compare a dash both ways, dropped and as a space: Min-Jun matches Minjun, Jean-Pierre matches Jean Pierre, and a dashed record word also offers its parts, so Wei matches in Qian-Wei
- When
doi or pmid is provided (bare or as a URL), uses doi-self or pmid-self as an anchor — researchers who have linked that work to their ORCID record are near-deterministic matches
- Accepts a full name (
Jennifer Doudna), a byline with initials (J. Doudna, Jennifer A. Doudna), or Family, Given (Doudna, Jennifer, read as Jennifer Doudna); an initial counts toward a partial match when the candidate's first given name starts with it
- Searches the exact name phrase first, so a name that matches as written sends one query. Each later stage runs only when every earlier one found nothing: the byline form of any initials with the affiliation, then the phrase and the byline without it, then the other names listed on ORCID records, then each supplied anchor alone
- No synthetic scores — raw signal fields only, so callers can apply their own ranking logic
orcid://researcher/{orcid_id}/profile resource
- Returns name, other names, biography, keywords, researcher URLs, and external identifiers as
application/json
{orcid_id} is the bare iD, with an X or x check digit — a URI segment cannot carry the https://orcid.org/ form
- Fails with a typed
data.reason and a recovery hint, like the tools: invalid_orcid_id for a checksum-invalid iD (rejected locally, before any upstream call), profile_not_found for an iD ORCID does not know or a record with no public name
- Prefer the
orcid_get_profile tool when the response needs to flow into conditional logic
orcid://researcher/{orcid_id}/works resource
- Returns the first 25 works plus
workCount (the total available) as application/json
{orcid_id} is the bare iD, with an X or x check digit
- Fails with
invalid_orcid_id (checksum, before any upstream call) or profile_not_found (unknown iD, data.orcidId included), each with a recovery hint
- No cursor pagination on this resource — use the
orcid_get_works tool to page the full list or filter results
- DOIs and PMIDs in the response are ready for Crossref or PubMed chaining
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.
ORCID-specific:
- ORCID Public API v3.0 (
https://pub.orcid.org/v3.0) — no API key required for public read endpoints
expanded-search as the primary search backend — returns ORCID iD, name, and institution data inline, eliminating N+1 profile fetches
- Single
/activities call for affiliation queries, filtered client-side — eliminates up to 7 parallel upstream calls vs. per-section fetching
- External identifiers (DOIs, PMIDs, arXiv IDs) surfaced in works responses in formats ready for cross-server chaining to Crossref, PubMed, or arXiv
- Inline markup that depositing systems leave in work titles, abstracts, and funding and research-resource titles (
<i>, <sup>, <h4>) is stripped to plain text; the deposited citation is relayed verbatim
Agent-friendly output:
- Provenance —
orcid_resolve_researcher returns raw disambiguation signals (name match type, institution overlap, anchor type) instead of a synthetic confidence score
- Who asserted each item — every record from the six activity tools carries
sources: the person or member organization that added it (a university system, funder, Crossref, Web of Science) and whether the researcher asserted it (selfAsserted); grouped works and funding list every source in the group
- Truncation awareness — pages are sized by count alone and a request over a tool's cap returns the cap with a notice;
orcid_search_researchers reports numFound and a truncated flag against the ORCID Public API's 10,000-offset ceiling, with nextStart to continue; orcid_get_works reports workCount, matchedCount, and truncated against the requested page, and orcid_get_peer_reviews totalCount and truncated, each with nextOffset to continue; orcid_get_research_resources detail reports truncated with nextItemOffset
- Merged accounts — a deprecated ORCID iD is served from the primary record it was merged into, reported under the primary iD with a notice naming both, including on the three endpoints ORCID does not redirect (bulk work detail, research resources, allocation detail), where a
/person merge check finds the primary iD; if that check cannot run, the answer opens with a notice that its empty or not-found result is unconfirmed and to call again
- Partial failure isolation —
orcid_get_work_detail returns per-put-code errors alongside successfully resolved works instead of failing the whole batch, and names any put-codes past the 100-code fetch cap or missing from ORCID's answer
- Empty-result guidance —
orcid_get_works, orcid_get_affiliations, orcid_get_funding, orcid_get_peer_reviews, and orcid_get_research_resources return a notice when a result is empty, explaining that this may mean neither the researcher nor a member organization added entries, or that visibility settings hide them, rather than confirmed absence; orcid_get_profile names each section with no public data
- Record text marked as data — in the text output, biographies and abstracts render as blockquotes, names, titles, and organization names are kept to one line, and a deposited citation sits in a code fence it cannot close, so text a researcher or depositing system wrote never reads as the server's own headings or labels;
structuredContent carries every value verbatim
Getting started
Connect to the hosted instance, no install:
Or run it locally:
For other clients, add this to the MCP config file:
No API key is required: the ORCID Public API is open for public read access, for non-commercial use under ORCID Public API ToS §2. For Docker or a source build, see Running the server.
Configuration
All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:
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 v24+).
-
Clone and install:
-
Build and run:
-
Run checks and tests:
Docker
The image defaults to HTTP transport, stateless session mode, and logs to /var/log/orcid-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/orcid-mcp-server:latest"]. To build locally, docker build -t orcid-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 request-scoped logging, ctx.state for tenant-scoped storage
- Register new tools and resources in the
createApp() arrays
- Wrap ORCID API calls: validate raw response → normalize to domain type → return output schema; never fabricate missing fields
Contributing
Issues are welcome. Run checks and tests before submitting:
License
Apache-2.0 — see LICENSE for details.