crossref-mcp-server

Search Journals

crossref_search_journals

Read-only

Finds Crossref journal records by ISSN or title query. Provide issn for an exact single-journal lookup, or query for title-based search returning up to rows results. Title-query results page with offset — the nextOffset enrichment carries the value for the following page, up to offset + rows = 100000. Set include_works to true to also return a page of the matched journal's most recent works; that list pages two ways, in two orders. works_offset is the simple one: newest published first, capped ten times lower at works_offset + rows = 10000. works_cursor has no ceiling and reaches the whole works list, newest registered first — ordered by the date each DOI was registered with Crossref, since Crossref does not walk a publication-date sort by cursor: pass works_cursor="*" on the first call, then chain the nextWorksCursor token from each response. The two cannot be combined, and a cursor walk always starts at the most recently registered work — it cannot resume from an offset. Returns journal metadata: title, publisher, ISSN-L, subject areas, and total DOI count.

Input Schema

TableJSON Schema

Name	Required	Description
`issn`	No	ISSN for exact single-journal lookup (print or electronic, with or without hyphen). Example: "1234-5678".
`rows`	No	Maximum number of journals to return for title queries, or works when include_works is true (1–100, default 10)
`query`	No	Journal title search query, e.g. "Nature" or "Journal of Machine Learning Research"
`offset`	No	Zero-based offset into the title-query journal list. Pass the nextOffset value from the previous response to continue. Ignored when issn is set, which resolves exactly one record.
`works_cursor`	No	Cursor token for deep paging of the journal works list when include_works is true. Pass "*" to start the walk at the most recently registered work, then pass the nextWorksCursor value from each response. A walk runs by the date each DOI was registered with Crossref, newest first, not by publication date — Crossref does not walk a publication-date sort by cursor. Has no offset ceiling and cannot be combined with works_offset.
`works_offset`	No	Zero-based offset into the journal works list when include_works is true. Pass the nextWorksOffset value from the previous response to continue. Capped at works_offset + rows = 10000; use works_cursor to read the whole list. Cannot be combined with works_cursor.
`include_works`	No	When true, also return a page of the journal's most recent works — newest published first on an offset page, newest registered first on a works_cursor walk. Requires an unambiguous journal — pass issn when a title query matches more than one. A journal with no ISSN registered has no addressable works list; the works lookup is then skipped and the notice enrichment says so.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance on a page that needs a caveat: a query nothing matched, an offset or works_offset past the end of a list that did match, a page that stops at one of the route offset ceilings with records still unretrieved, an include_works request that was skipped because the matched journal has no registered ISSN to address its works list by, or a query or issn supplied blank with nothing else to search by, so the page lists every journal unfiltered. Absent otherwise. A page needing more than one caveat carries them all in this one string.
`journals`	No	Matching journal records
`nextOffset`	No	Value to pass as offset on the next call for the following page of journals. Absent when this page ends the matches or the next page would breach the 100000-record offset ceiling.
`worksTotal`	No	Total works count for the journal, when include_works is true
`recentWorks`	No	Page of works from the matched journal, newest first — by publication date on an offset page, by Crossref registration date on a works_cursor page. Requires include_works, and absent even then when the matched journal has no registered ISSN — the works list is addressable by ISSN alone, and the notice enrichment says so.
`journalCount`	No	Number of journal records returned in this page
`journalsTotal`	No	Total journal records matching the query in Crossref
`nextWorksCursor`	No	Value to pass as works_cursor on the next call for the following page of works. Present only on a page requested with works_cursor, and absent once the walk reaches the end of the works list.
`nextWorksOffset`	No	Value to pass as works_offset on the next call for the following page of works. Absent when this page ends the works list, the next page would breach the 10000-record offset ceiling, or the page was requested with works_cursor.

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedSep 24, 2026

changedInput schema / properties / include_works / description

Previous value: -"When true, also return a page of the journal's most recent works by publication date. Requires an unambiguous journal — pass issn when a title query matches more than one. A journal with no ISSN registered has no addressable works list; the works lookup is then skipped and the notice enrichment says so."New value: +"When true, also return a page of the journal's most recent works — newest published first on an offset page, newest registered first on a works_cursor walk. Requires an unambiguous journal — pass issn when a title query matches more than one. A journal with no ISSN registered has no addressable works list; the works lookup is then skipped and the notice enrichment says so."

addedInput schema / properties / issn / anyOf

Added value: +[
+  {
+    "const": "",
+    "type": "string"
+  },
+  {
+    "description": "ISSN, e.g. \"1234-5678\"",
+    "pattern": "^\\d{4}-?\\d{3}[\\dX]$",
+    "type": "string"
+  }
+]

removedInput schema / properties / issn / pattern
```
Removed value: -"^\\d{4}-?\\d{3}[\\dX]$"
```
removedInput schema / properties / issn / type
```
Removed value: -"string"
```

changedInput schema / properties / rows / type

Previous value: -"number"New value: +"integer"

changedInput schema / properties / works_cursor / description

Previous value: -"Cursor token for deep paging of the journal works list when include_works is true. Pass \"*\" to start the walk at the newest work, then pass the nextWorksCursor value from each response. Has no offset ceiling and cannot be combined with works_offset. Each token runs about 1500 characters and is returned on both result surfaces, a fixed cost per page — raise rows to spread it across more works on a long walk."New value: +"Cursor token for deep paging of the journal works list when include_works is true. Pass \"*\" to start the walk at the most recently registered work, then pass the nextWorksCursor value from each response. A walk runs by the date each DOI was registered with Crossref, newest first, not by publication date — Crossref does not walk a publication-date sort by cursor. Has no offset ceiling and cannot be combined with works_offset."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `rate_limited`: Crossref answered HTTP 429 and the limit did not clear inside the retry budget. `upstream_unavailable`: Crossref was unreachable, returned a 5xx status, or served an HTML error page instead of JSON. `malformed_response`: Crossref returned HTTP 200 with a body that is not valid JSON. `request_timeout`: Crossref did not respond within CROSSREF_TIMEOUT_MS, or answered HTTP 408/504. `issn_not_found`: ISSN lookup returned 404 — ISSN is not registered in Crossref. `ambiguous_journal`: include_works is true but the title query matched more than one journal, making the target ambiguous. `offset_too_large`: offset + rows exceeds the 100000-record ceiling Crossref allows on journal title search. `works_offset_too_large`: works_offset + rows exceeds the 10000-record ceiling Crossref allows on a journal works list. `works_cursor_offset_conflict`: include_works is true and works_cursor was supplied alongside a works_offset above zero. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `rate_limited`: Crossref answered HTTP 429 and the limit did not clear inside the retry budget. `upstream_unavailable`: Crossref was unreachable, returned a 5xx status, or served an HTML error page instead of JSON. `malformed_response`: Crossref returned HTTP 200 with a body that is not valid JSON. `request_timeout`: Crossref did not respond within CROSSREF_TIMEOUT_MS, or answered HTTP 408/504. `invalid_cursor`: Crossref did not recognize the cursor token (HTTP 404 cursor-invalid). `invalid_parameter`: Crossref rejected a parameter value (a filter value of the wrong type or form), or answered HTTP 400 with a body that did not parse. `issn_not_found`: ISSN lookup returned 404 — ISSN is not registered in Crossref. `ambiguous_journal`: include_works is true but the title query matched more than one journal, making the target ambiguous. `offset_too_large`: offset + rows exceeds the 100000-record ceiling Crossref allows on journal title search. `works_offset_too_large`: works_offset + rows exceeds the 10000-record ceiling Crossref allows on a journal works list. `works_cursor_offset_conflict`: include_works is true and works_cursor was supplied alongside a works_offset above zero. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "rate_limited",
-  "upstream_unavailable",
-  "malformed_response",
-  "request_timeout",
-  "issn_not_found",
-  "ambiguous_journal",
-  "offset_too_large",
-  "works_offset_too_large",
-  "works_cursor_offset_conflict"
-]New value: +[
+  "rate_limited",
+  "upstream_unavailable",
+  "malformed_response",
+  "request_timeout",
+  "invalid_cursor",
+  "invalid_parameter",
+  "issn_not_found",
+  "ambiguous_journal",
+  "offset_too_large",
+  "works_offset_too_large",
+  "works_cursor_offset_conflict"
+]

changedOutput schema / properties / notice / description

Previous value: -"Guidance on a page that needs a caveat: a query nothing matched, an offset past the end of a list that did match, a page that stops at one of the route offset ceilings with records still unretrieved, or an include_works request that was skipped because the matched journal has no registered ISSN to address its works list by. Absent otherwise."New value: +"Guidance on a page that needs a caveat: a query nothing matched, an offset or works_offset past the end of a list that did match, a page that stops at one of the route offset ceilings with records still unretrieved, an include_works request that was skipped because the matched journal has no registered ISSN to address its works list by, or a query or issn supplied blank with nothing else to search by, so the page lists every journal unfiltered. Absent otherwise. A page needing more than one caveat carries them all in this one string."

changedOutput schema / properties / recentWorks / description

Previous value: -"Page of works from the matched journal, ordered by publication date (newest first). Requires include_works, and absent even then when the matched journal has no registered ISSN — the works list is addressable by ISSN alone, and the notice enrichment says so."New value: +"Page of works from the matched journal, newest first — by publication date on an offset page, by Crossref registration date on a works_cursor page. Requires include_works, and absent even then when the matched journal has no registered ISSN — the works list is addressable by ISSN alone, and the notice enrichment says so."

First observedSep 19, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint and openWorldHint. The description adds substantial behavioral context: offset paging caps at offset + rows = 100000, works_offset is capped at 10000, works_cursor has no ceiling, cursor walks order by DOI registration date rather than publication date, initial cursor must be '*', and include_works skips the works lookup when no ISSN is registered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but the complexity of seven parameters and multiple pagination modes justifies it. Every sentence carries operational value, and the structure front-loads the core purpose, then explains exact-lookup versus title search, then pagination modes, then edge cases. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only open API tool with seven optional parameters and rich pagination behavior, the description covers all decision points: how to start, how to page, which limit applies, which ordering to expect, what cannot be combined, and what happens with journals lacking ISSN. The output schema already covers return fields, so nothing needed for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains the exact single-journal behavior of issn, the nextOffset enrichment, the offset ceiling, the cursor initialization and chaining, the ordering difference between offset and cursor pagination, and the constraint that cursor and offset cannot be combined.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Finds Crossref journal records by ISSN or title query.' It clearly distinguishes this tool from sibling tools like crossref_search_works and crossref_get_work by focusing on journal records rather than works, funders, or members.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit selection rules: use issn for exact single-journal lookup, use query for title-based search, and use include_works to also retrieve works. It also states when-not conditions, such as 'The two cannot be combined,' and explains when to choose works_offset versus works_cursor based on depth and ordering needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All crossref-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.