convez.ai
MCP ServerBusca & PesquisaIntermediário
cyanheads

Crossref MCP Server

cyanheads/crossref-mcp-server

Resolve DOIs e busca 155M trabalhos acadêmicos via Crossref

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que acessa a API Crossref para resolver DOIs, buscar ~155M trabalhos acadêmicos e recuperar referências bibliográficas. Oferece 5 ferramentas especializadas em metadados de publicações científicas, com suporte a STDIO e HTTP streamável.

Instalação

$npx convez-ai cyanheads/crossref-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 dia
Versão
v0.5.4
Issues abertas
3
Contribuidores
1

Casos de uso

  • Pesquisadores buscando metadados de artigos científicos por DOI
  • Análise de citações e redes de referências entre publicações
  • Integração de dados bibliográficos em sistemas de gestão acadêmica
  • Busca estruturada em repositório global de publicações

Veredito

Ferramenta especializada e bem construída para acesso estruturado ao Crossref. Ideal para pesquisadores e sistemas que precisam de metadados confiáveis de publicações científicas. Integração sólida com MCP e suporte multiplataforma.

README

A tradução para o português deste README ainda está na fila.

Version License Docker MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework


Tools

Five tools for working with Crossref data — DOI resolution, full-text search across all scholarly works, outgoing reference lists, and journal/funder lookup:

ToolDescription
crossref_get_workResolve a DOI to its full Crossref metadata record: title, authors, affiliations, abstract (when deposited), journal, publication date, type, license, full-text links, funder acknowledgements, and outgoing reference list
crossref_search_worksSearch the Crossref works index by free text and/or structured filters. Supports sort, field selection, and cursor-based deep paging.
crossref_get_referencesReturn the outgoing reference list for a DOI — the works cited by this paper, with raw citation strings and resolved DOIs where available
crossref_search_journalsFind Crossref journal records by ISSN or title query; optionally retrieve the journal's most recent works
crossref_search_fundersFind funders registered in the Crossref Funder Registry by name or funder DOI; optionally retrieve funded works

crossref_get_work

Resolve a DOI to its canonical Crossref record.

  • DOI validated against 10.NNNN/suffix regex before the upstream call
  • Returns title, authors with affiliations, abstract (when deposited), container/journal, publication date, work type, ISSN, license URLs, full-text link URLs, and funder acknowledgements
  • Incoming citation count (is-referenced-by-count) is included; citing works are not — Crossref does not expose that data. Use OpenAlex for citation graphs.

crossref_search_works

Search across ~155M Crossref-registered works.

  • Free-text query plus a structured filter object using Crossref's hyphen-separated key syntax: from-pub-date, until-pub-date, type, funder, issn, member, has-abstract, has-references, has-full-text, directory (use DOAJ to restrict to open-access content)
  • Sort by relevance, is-referenced-by-count, published, deposited, or score
  • fields parameter narrows response payload — useful for large result sets
  • Offset paging up to ~10K results; deep paging requires cursor=* on the first call, then pass the returned next-cursor token. Cursor and offset cannot be combined.

crossref_get_references

Fetch the outgoing reference list for a DOI.

  • Each reference includes its raw citation string and, where Crossref has resolved it, a DOI for follow-up lookup
  • Coverage varies by publisher — pre-2000 literature and non-participating publishers may have no reference list
  • Single-hop only; agents that need N-hop traversal chain calls explicitly

crossref_search_journals

Find journal records by ISSN or title.

  • include_works: true triggers a second upstream call to fetch the journal's most recent works
  • Returns journal title, publisher, ISSN-L, subject areas, and DOI prefix

crossref_search_funders

Find funders in the Crossref Funder Registry.

  • Accepts a name query or a direct funder DOI
  • include_works: true retrieves funded works for the matched funder
  • Returns funder name, DOI, country, and alternate names

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
  • STDIO and Streamable HTTP transports

Crossref-specific:

  • Polite-pool User-Agent header injected on every request — priority access granted via CROSSREF_MAILTO email address, no API token required
  • withRetry: 3 attempts, exponential backoff, handles both 429 and 503 responses
  • Cursor-based deep paging for result sets beyond the ~10K offset cap
  • Filter key validation: Crossref uses hyphens (has-abstract, has-references, from-pub-date); the server enforces correct syntax and surfaces API validation errors with actionable recovery hints

Getting started

Add the following to your MCP client configuration file. CROSSREF_MAILTO is optional but recommended — without it the server uses Crossref's anonymous pool with stricter rate limits.

{
  "mcpServers": {
    "crossref-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/crossref-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "CROSSREF_MAILTO": "your-email@example.com"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "crossref-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/crossref-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "CROSSREF_MAILTO": "your-email@example.com"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "crossref-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "CROSSREF_MAILTO=your-email@example.com",
        "ghcr.io/cyanheads/crossref-mcp-server:latest"
      ]
    }
  }
}

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

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 CROSSREF_MAILTO=your-email@example.com bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

  • Bun v1.3.11 or higher (or Node.js v24+).
  • An email address for CROSSREF_MAILTO is optional but recommended — Crossref's polite pool grants priority access to clients that identify themselves. No account or token is required.

Installation

  1. Clone the repository:
git clone https://github.com/cyanheads/crossref-mcp-server.git
  1. Navigate into the directory:
cd crossref-mcp-server
  1. Install dependencies:
bun install
  1. Configure environment:
cp .env.example .env
# edit .env and optionally set CROSSREF_MAILTO for polite-pool access

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts.

VariableDescriptionDefault
CROSSREF_MAILTOEmail address embedded in the polite-pool User-Agent header. Optional — server starts without it but logs a warning and uses the anonymous pool with stricter rate limits.—
CROSSREF_BASE_URLCrossref API base URL. Override for testing against a local proxy.https://api.crossref.org
CROSSREF_TIMEOUT_MSPer-request timeout in milliseconds.10000
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTPort for the HTTP server.3010
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (RFC 5424).info
LOGS_DIRDirectory for log files (Node.js only).<project-root>/logs
OTEL_ENABLEDEnable OpenTelemetry instrumentation.false

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

Running the server

Local development

  • Build and run:

    # One-time build
    bun run rebuild
    
    # Run the built server
    bun run start:stdio
    # or
    bun run start:http
    
  • Run checks and tests:

    bun run devcheck   # Lint, format, typecheck, security
    bun run test       # Vitest test suite
    bun run lint:mcp   # Validate MCP definitions against spec
    

Project structure

DirectoryPurpose
src/index.tscreateApp() entry point — registers tools and inits services.
src/configServer-specific environment variable parsing and validation with Zod.
src/mcp-server/toolsTool definitions (*.tool.ts). Five tools for Crossref data access.
src/services/crossrefCrossrefService — HTTP client, polite-pool header, retry, pagination helpers.
tests/Unit and integration tests mirroring src/.

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 via the barrel in src/mcp-server/tools/definitions/index.ts
  • Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields (abstracts, reference lists, and affiliations are frequently absent in Crossref records)

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.

Ver o original no GitHub

Bom para

Relacionados