NASA SciX MCP Server
This MCP server lets an LLM search and analyze astronomical literature through the SciX API, manage personal libraries and their sharing/annotations, and export bibliographic data.
Literature search: Solr-syntax queries (author, title, abstract, year ranges, Boolean operators) with pagination, sorting (score, citations, date, reads), and markdown or JSON output.
Paper details: Fetch metadata for a specific paper by its SciX bibcode.
Citation metrics: Compute h-index, citation counts, and usage statistics for up to 2000 bibcodes.
Citation network: List papers that cite a given paper (forward citations) or that it references (backward citations).
Export: Generate citations in 25+ formats (BibTeX, AASTeX, EndNote, RIS, IEEE, MNRAS, etc.), including custom templates, key/journal formatting, and author limits.
Library management: List, view, create, delete, and edit libraries; add or remove documents; add documents from a search query; and run set operations (union, intersection, difference, copy, empty).
Permissions & sharing: View library permissions, grant or modify user access, and transfer library ownership.
Annotations: Get, add/update, or delete notes on documents within a library.
Documentation search: Search SciX help docs for search syntax, features, and API usage guidance.
Provides access to the NASA Astrophysics Data System (SciX) for searching astronomical literature, retrieving paper metadata, calculating citation metrics, exploring citation networks, exporting bibliographic data in multiple formats, and managing personal libraries of papers.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@NASA SciX MCP Server find top cited exoplanet papers from 2023"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
SciX MCP Server
A Model Context Protocol (MCP) server for the SciX API. This server enables LLMs to search astronomical literature, retrieve paper metadata, analyze citation metrics, and export bibliographic data.
Quick Start (MCP clients)
Get an API Key
Create an account at SciX
Generate an API token at https://scixplorer.org/user/settings/token
Set the environment variable:
export SCIX_API_TOKEN=your_api_key_hereOr create a .env file:
cp .env.example .env
# Edit .env and add your keyConfigure your MCP client (Claude, Codex, etc.)
Add to your MCP client configuration:
{
"mcpServers": {
"scix": {
"command": "npx",
"args": ["scix-mcp"],
"env": {
"SCIX_API_TOKEN": "your_api_key_here"
}
}
}
}Common locations: Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %AppData%\\Claude\\claude_desktop_config.json on Windows) and Codex CLI (~/.config/codex/config.json). Restart your client after editing.
Local MCP clients that read .mcp/server.json can also pick up the packaged config in .mcp/server.json; just drop in your SCIX_API_TOKEN.
Environment variables
SCIX_API_TOKEN(required for stdio): your SciX API key. Not used by the HTTP transport, which takes the token from each request.SCIX_API_BASE(optional): override the API base URL. Defaults tohttps://api.scixplorer.org/v1when unset. Primarily used to point the server at a local mock during the e2e test suite.SCIX_WEB_BASE(optional): override the host used when building the scixplorer.org links in tool output. Defaults tohttps://scixplorer.org.PORT/HOST(HTTP only): where the HTTP transport listens. Default8000on0.0.0.0.
Related MCP server: Scopus MCP Server
HTTP transport
scix-mcp-http serves the same tools over Streamable HTTP instead of stdio:
POST /mcp for JSON-RPC, GET /healthz as an unauthenticated probe.
Unlike stdio, the server holds no token of its own — each request must carry the caller's, and requests without one get a 401:
Authorization: Bearer <your SciX API token>Tool calls act as the calling user and spend that user's rate limit. Clients that cannot set the header (ChatGPT connectors, which need OAuth or no auth) cannot use this endpoint.
Example Prompts
- Find refereed JWST exoplanet papers from 2022-2024 sorted by citation_count, return the top 5 in markdown with bibcodes, titles, first author, and citation counts.
- Build a query for gravitational wave kilonova follow-ups since 2017 (fielded abstract search), add the first 50 results to library <library_id>, and then give me metrics (h-index, total cites) for those bibcodes in JSON.
- Fetch paper 2020ApJ...905....3A, list its first 10 references with titles, and also list the first 10 forward citations with publication years.
- Create a public library named “Cosmic Web Reviews”, seeded with bibcodes [...], then share the public URL and export the contents in BibTeX.
- For bibcodes [...], return citation metrics plus a ranked list of which papers cite the most recent one (rows=25) in markdown.
- Get all my libraries, pick the one with the most documents, and return its metadata plus the first 5 document titles in JSON.Features
Literature Search: Full-text search with advanced Solr query syntax
Faceting: Break a result set down by any of the 16 SciX facets and feed the counts back as filters via the
get_facetstoolPaper Details: Retrieve metadata for any publication
Citation Metrics: Calculate h-index, citation counts, and usage statistics
Citation Network: Explore forward and backward citations
Export: Generate citations in 23 bibliographic formats (BibTeX, AASTeX, EndNote, RIS, and more) — see the
exporttool'sformatenum insrc/types.tsfor the full listDocumentation Search: Query SciX help/docs content via the
search_docstoolHealth Check: Diagnose setup (token, API reachability, tool registry) via the
health_checktoolDual Format: Support for both human-readable Markdown and machine-readable JSON
Available Tools
Search & Metadata
search: Solr-powered search across SciX. Params:query(required),filter_query(up to 20 Solrfqstrings, each sent as its own repeated parameter and ANDed together),rows(1-100, default 10),start(offset, default 0),sort(score desc|citation_count desc|date desc|date asc|read_count desc, defaultscore desc),response_format(markdown|json, defaultmarkdown).Example queries:
author:"Einstein, A." title:relativity,black holes year:2020-2023,author:^Smith,dark energy AND galaxy clusters.
get_facets: Count how a result set breaks down across facets, so a search can be narrowed. Params:query(required),filter_query,facets(defaultauthor,year,publications,keywords,refereed,collections),limit(1-200 buckets per facet, default 10),sort(count desc|count asc|index asc|index desc),prefix(drill into a hierarchy; only valid with exactly one facet),response_format.Every bucket carries a
filterstring ready to pass straight back as asearchfilter_queryentry.Available facets, with the Solr field each one counts:
Facet
Solr field
Hierarchical
authorauthor_facet_hieryes (2 levels)
collectionsdatabaseno
refereedpropertyno
institutionsaff_facet_hieryes (2 levels)
keywordskeyword_facetno
publicationspub_abbrevno
bibgroupsbibgroup_facetno
simbadsimbad_object_facet_hieryes (2 levels)
nedned_object_facet_hieryes (2 levels)
awardgrant_facet_hieryes (2 levels)
datadata_facetno
viziervizier_facetno
pubtypedoctype_facet_hieryes (2 levels)
planetaryplanetary_feature_facet_hier_3levelyes (3 levels)
uatuatno
yearyearno
Hierarchical facet values are prefixed with their level, e.g.
0/Smith, Jat the root and1/Smith, J/Smith, Johnone level down. Expandable buckets report achild_prefixto pass back asprefix.
get_paper: Fetch a paper bybibcode, DOI, arXiv ID, or SciX ID (scix:...) with optionalresponse_format.get_metrics: Metrics forbibcodes(1-2000) with optionalresponse_format; returns h-index, g-index, citation counts, usage stats.
Citation Network
get_citations: Forward citations for a paper (bibcode, DOI, arXiv ID, or SciX ID); optionalrows(1-100, default 20) andresponse_format.get_references: Backward references for a paper (bibcode, DOI, arXiv ID, or SciX ID); optionalrows(1-100, default 20) andresponse_format.
Export
export: Exportbibcodes(1-2000) informat— one of the 23 formats in theExportInputSchemaenum insrc/types.ts(e.g.bibtex,aastex,endnote,ris,ieee,mnras). Usecustom_formatwithformat: customfor a template. Returns plain text in the chosen format.
Documentation
search_docs: Search SciX help documentation. Params:query(required, natural language),limit(1-20, default 5). Returns a ranked list with title, section/subsection, source URL, relevance score, and a focused snippet.
Libraries
get_libraries: List libraries; optionaltype(all|owner|collaborator, defaultall) andresponse_format.get_library: Metadata + documents forlibrary_id; optionalresponse_format.create_library: Create withname(required), optionaldescription,public(defaultfalse),bibcodes, andresponse_format.delete_library: Permanently delete bylibrary_id; optionalresponse_format.edit_library: Updatename,description, orpublicforlibrary_id; optionalresponse_format.manage_documents: Add/remove documents withlibrary_id,bibcodes(1-2000),action(add|remove), and optionalresponse_format.add_documents_by_query: Add search results to a library withlibrary_id,query, optionalrows(1-2000, default 25), andresponse_format.library_operation: Run set ops on a library withlibrary_id,operation(union|intersection|difference|copy|empty), optionalsource_library_ids,name/description/public(only forunion/intersection/difference, which create a new library), andresponse_format. Forcopy,source_library_idsholds the destination library;emptyuses none of these.
Permissions & Sharing
get_permissions: View owners/collaborators forlibrary_id; optionalresponse_format.update_permissions: Grant, change, or revoke a user's access withlibrary_id,email,permission(read|write|admin|none), and optionalresponse_format.nonerevokes all access; ownership moves viatransfer_libraryinstead.transfer_library: Transfer ownership withlibrary_id,email, and optionalresponse_format.
Annotations
get_annotation: Fetch note content forlibrary_id+bibcode; optionalresponse_format.manage_annotation: Add/update note withlibrary_id,bibcode,content, and optionalresponse_format.delete_annotation: Remove note forlibrary_id+bibcode; optionalresponse_format.
Diagnostics
health_check: Diagnose the server setup. No required params (optionalresponse_format). Reports server name/version, API base URL, whether a token is configured, an authentication probe result (ok|unauthorized|rate_limited|unreachable|skipped), and the registered tool names. Never emits the token value. Runs without a token (probe isskipped); use it to tell setup problems apart from ordinary API errors.
Rate Limits
Limits are per-endpoint, not a single account-wide daily cap
The
X-RateLimit-LimitandX-RateLimit-Remainingresponse headers are authoritative; a 429 error reports whichever of them the response includesRequest higher limits at https://scixplorer.org/feedback/general
SciX Search Syntax
The SciX search supports Solr query syntax:
Syntax | Description | Example |
| Exact author |
|
| First author |
|
| Title search |
|
| Abstract search |
|
| Year range |
|
| Refereed only |
|
| Papers citing X |
|
| Papers cited by X |
|
| Boolean operators |
|
Values discovered through get_facets are better applied as filter_query
entries than folded into query: Solr caches filters separately, and the
facet/filter split is what the SciX web UI does.
Outbound request tagging
Every request this server makes to the SciX API carries:
X-Client-Source: scix-mcp— a stable, low-cardinality tag so SciX access logs can attribute MCP traffic without parsing User-Agent.User-Agent: scix-mcp/<version> (transport=stdio|http)— version and transport detail.
Development
Install & Build
pnpm install
pnpm buildLocal commands
# Watch mode
pnpm dev
# Test with MCP Inspector
npx @modelcontextprotocol/inspector node build/index.jsTesting
The project uses Vitest.
Running Tests
# Run all tests
pnpm test
# Run tests in watch mode
pnpm test:watch
# Run tests with coverage
pnpm test:coverage
# Run the end-to-end protocol smoke suite (builds first, then drives the
# built server over stdio against a local mock SciX API)
pnpm test:e2e
# Run the agent evals (costs tokens; needs the `claude` CLI on PATH)
pnpm test:aiThe e2e suite (test/e2e/protocol.test.ts) spawns node build/index.js,
connects a real MCP client over stdio, and asserts the live tool/prompt/
resource surface plus one canned call per tool. It points the server at a
local mock via the SCIX_API_BASE environment variable (see below); no real
network access is required.
Agent Evals
pnpm test:ai runs test/ai/library-workflow.test.ts, which asks a real
lightweight agent (claude -p --model haiku) to do a task and then asserts
which tools it called and what the server stored. This catches the class of
bug unit tests cannot see: a tool that returns a cheerful success message
while doing nothing useful, a misleading tool description that sends the
agent down a two-step path, or a mutating tool fired for a read-only
question.
Harness properties:
Opt-in. The suite skips unless
SCIX_AI_EVALS=1, which thetest:aiscript sets.pnpm testand CI stay deterministic and free.Hermetic. Each run gets the same local mock SciX API the e2e suite uses, so evals never touch a real account. The harness passes
--strict-mcp-config; without it the developer's own MCP servers attach, including anyscixserver pointed at production, and a "create a library" prompt could mutate real data.Non-deterministic. Assertions target tool names, request payloads, and stored state — not prose. The config retries once, and each test prints the tool sequence and cost so a failure shows the path the agent took.
Cheap. The four scenarios run in about 40 seconds for roughly $0.11 total.
Add a scenario by calling runAgent({ prompt, apiBase: mock.url }) and
asserting on the returned toolNames, toolCalls, and mock state.
Test Structure
Tests are organized in the test/ directory:
test/
├── helpers/
│ └── mockFetch.ts # Fetch mocking utilities
├── client.test.ts # HTTP client tests
├── search-docs.test.ts # Documentation search tests
└── tools/
├── search.test.ts # Search tool tests
├── facets.test.ts # Facet counts tool tests
├── paper.test.ts # Paper details tests
├── metrics.test.ts # Metrics tests
├── citations.test.ts # Citations/references tests
├── export.test.ts # Export tests
└── library.test.ts # Library management testsTest Coverage
The test suite covers:
HTTP Client: GET/POST/PUT/DELETE methods, error handling (401/404/429), timeouts, request formatting
Search Tools: Query parameter encoding, repeated
fqfilters, pagination, result limiting, response formattingFacets: Registry/field mapping,
json.facetrequest bodies, hierarchical prefix handling, bucket parsingPaper Tools: Bibcode validation, field selection, error handling for missing papers
Metrics Tools: Batch bibcode processing, MAX_BIBCODES limits, metric type selection
Citation Tools: Forward/backward citations, sorting, row limits
Export Tools: Multiple export formats (BibTeX, AASTeX, EndNote, etc.), batch processing
Library Tools: All CRUD operations, permissions, annotations, library operations
API Token for Tests
Tests use mock fetch and don't require a real API token. Individual tests set SCIX_API_TOKEN='test-api-key' as needed.
Project Structure
src/
├── index.ts # Main server entry point
├── client.ts # SciX API client wrapper
├── types.ts # TypeScript/Zod type definitions
├── formatters.ts # Response formatting utilities
├── config.ts # Configuration constants
├── identifier-query.ts # Identifier (bibcode/DOI/arXiv/SciX) resolution
├── facets.ts # Facet registry, json.facet building, bucket parsing
├── scix-urls.ts # scixplorer.org link builders
├── search-docs.ts # Offline docs search (search_docs tool)
└── tools/
├── search.ts # Search tool
├── facets.ts # Facet counts tool
├── paper.ts # Paper details tool
├── metrics.ts # Metrics tool
├── citations.ts # Citation network tools
├── export.ts # Export tool
└── library.ts # Library management toolsExample Usage
Search for papers
Use search with query "supernova 2023" to find recent supernova papersNarrow a search with facets
Use get_facets with query "exoplanet atmospheres" to see the top authors,
journals and years, then call search with the filter_query values it returns.Get paper details
Use get_paper with bibcode "2023ApJ...950..123S"Calculate metrics
Use get_metrics with bibcodes ["2023ApJ...950..123S", "2022MNRAS.517.1234T"]Export citations
Use export with bibcodes ["2023ApJ...950..123S"] and format "bibtex"Error Handling
The server provides clear error messages:
401: Token missing or rejected - check
SCIX_API_TOKEN(stdio) or theAuthorization: Bearerheader (HTTP)404: Resource not found - check bibcode format
429: Rate limit exceeded - wait until reset
Timeout: Request took > 30 seconds
Resources
License
MIT
Support
For API issues: https://scixplorer.org/feedback/general For server issues: Open an issue on GitHub
Available Tools
23 toolsadd_documents_by_queryC
Add documents to a library from a SciX search query.
Inputs: query (required), library_id (required), rows, response_format.
create_libraryB
Create a new library with optional initial documents.
Inputs: name (required), public, bibcodes, description, +1 more.
delete_annotationCDestructive
Delete an annotation/note for a document in a library.
Inputs: bibcode (required), library_id (required), response_format.
delete_libraryCDestructive
Delete a library permanently.
Inputs: library_id (required), response_format.
edit_libraryADestructiveIdempotent
Edit library metadata (name, description, public status). Overwrites the current values, and changing public status can expose a private library.
Inputs: library_id (required), name, public, description, +1 more.
exportBRead-only
Export citations in 23 bibliographic formats (BibTeX, AASTeX, EndNote, IEEE, MNRAS, etc.) with support for custom formatting templates.
Inputs: format (required), bibcodes (required), sort, keyformat, +4 more.
get_annotationCRead-onlyIdempotent
Get annotation/note for a document in a library.
Inputs: bibcode (required), library_id (required), response_format.
get_citationsBRead-onlyIdempotent
Get papers that cite a given paper (forward citations). Accepts a bibcode, DOI, arXiv ID, or SciX ID.
Inputs: bibcode (required), rows, response_format.
get_facetsARead-onlyIdempotent
Count how SciX search results break down across facets, to narrow a search. Covers author, collections, refereed, institutions, keywords, publications, bibgroups, SIMBAD objects, NED objects, award, data, Vizier tables, publication type, planetary features, UAT concepts, and year. Each returned bucket carries a ready-to-use filter_query value to pass back to search, and hierarchical facets (author, institutions, objects, award, publication type, planetary) report a child_prefix for drilling deeper.
Inputs: query (required), sort, limit, facets, +3 more.
get_librariesBRead-onlyIdempotent
Get all libraries for the authenticated user. Can filter by type (all, owner, collaborator).
Inputs: type, response_format.
get_libraryBRead-onlyIdempotent
Get details about a specific library including metadata and list of documents.
Inputs: library_id (required), response_format.
get_metricsBRead-onlyIdempotent
Get citation metrics including h-index, citation counts, and paper statistics for a list of bibcodes.
Inputs: bibcodes (required), response_format.
get_paperBRead-onlyIdempotent
Get detailed information about a specific paper by identifier: bibcode, DOI, arXiv ID, or SciX ID (scix:...).
Inputs: bibcode (required), response_format.
get_permissionsCRead-onlyIdempotent
Get permission information for a library.
Inputs: library_id (required), response_format.
get_referencesARead-onlyIdempotent
Get papers referenced by a given paper (backward citations). Accepts a bibcode, DOI, arXiv ID, or SciX ID.
Inputs: bibcode (required), rows, response_format.
health_checkARead-onlyIdempotent
Diagnose the SciX MCP server setup: reports server name and version, the API base URL, whether an API token is configured, an authentication probe result, and the registered tool names. Takes no required arguments. Use this to distinguish setup problems (missing/invalid token, unreachable API) from ordinary API errors.
Inputs: response_format.
library_operationBDestructive
Perform set operations on libraries (union, intersection, difference, copy, empty). The empty, difference and intersection actions replace or discard the contents of the target library.
Inputs: operation (required), library_id (required), name, description, +2 more.
manage_annotationADestructiveIdempotent
Add or update an annotation/note for a document in a library. Updating replaces the existing note content.
Inputs: bibcode (required), content (required), library_id (required), response_format.
manage_documentsADestructiveIdempotent
Add or remove documents from a library. Removal discards the record of those documents in that library.
Inputs: action (required), bibcodes (required), library_id (required), response_format.
searchARead-onlyIdempotent
Search SciX for astronomical literature. Supports full Solr query syntax including author:"Last, F.", title:keyword, abstract:keyword, year:2020-2023, and Boolean operators (AND, OR, NOT). Pass filter_query to narrow results by facet values obtained from get_facets.
Inputs: query (required), rows, sort, start, +2 more.
search_docsARead-onlyIdempotent
Search SciX help documentation for information about search syntax, features, API usage, and best practices.
Inputs: query (required), limit.
transfer_libraryADestructive
Transfer ownership of a library to another user. The current owner loses ownership and this server cannot undo it.
Inputs: email (required), library_id (required), response_format.
update_permissionsBDestructiveIdempotent
Grant or modify permissions for a user on a library. Can revoke access that an existing collaborator currently has.
Inputs: email (required), library_id (required), permission (required), response_format.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Tools are mostly distinct by resource and action: search vs search_docs, get_citations vs get_references, and the library CRUD/permission/annotation tools target different operations. A few library-modification tools (manage_documents, add_documents_by_query, library_operation) could be confused without reading descriptions, but the descriptions clarify boundaries.
The set follows a predictable snake_case pattern, mostly verb_noun (get_paper, create_library, delete_annotation, update_permissions). Minor deviations like search, export, health_check, and library_operation are readable but not strictly verb_noun.
23 tools is heavy for a literature API client, though the breadth of library lifecycle, permissions, annotations, citations, metrics, export, and diagnostics explains much of it. Some library-document operations could be consolidated, so the count borders on over-scoped.
Core literature workflows (search, paper retrieval, facets, citations/references, metrics, export) and library lifecycle including documents, permissions, annotations, and transfer are well covered. Minor gaps exist, such as a direct list-all-annotations operation, but agents can work around them.
Maintenance
Related MCP Connectors
Search arXiv/Semantic Scholar/OpenAlex + medical evidence (PubMed/Europe PMC) + LaTeX/PDF tools.
arXiv and OpenAlex/Crossref paper search (an open Google Scholar alternative) as agent tools.
Federated search of books and papers, BibTeX/RIS citations, open-access retrieval and reading.
Search INSPIRE-HEP papers, authors, experiments, HEPData records; get citation metrics and BibTeX.
Related MCP Servers
- AlicenseAqualityBmaintenanceProvides seamless access to the NASA Astrophysics Data System (ADS) for searching astronomical papers, tracking citations and metrics, managing paper libraries, and exporting BibTeX references through natural language conversation.1110MIT
- AlicenseAqualityDmaintenanceProvides access to the Elsevier Scopus API, enabling AI assistants to search for academic papers, retrieve detailed abstracts, and look up author profiles. It facilitates bibliometric research and scholarly data analysis through natural language commands.555MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to interact with the SciX (formerly NASA ADS) API to search scientific literature, export citations, and analyze bibliometric data. It supports advanced tools for managing libraries, resolving astronomical object names, and exploring citation networks.2MIT
- AlicenseNot gradedqualityDmaintenanceEnables agents to search, analyze, and explore arXiv academic papers with advanced multi-field search, author lookup, category browsing, citation extraction, and bibliography export.46 npmApache 2.0