Skip to main content
Glama
NASA SciX MCP Server

NASA SciX MCP Server

by adsabs

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

  1. Create an account at SciX

  2. Generate an API token at https://scixplorer.org/user/settings/token

  3. Set the environment variable:

export SCIX_API_TOKEN=your_api_key_here

Or create a .env file:

cp .env.example .env
# Edit .env and add your key

Configure 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 to https://api.scixplorer.org/v1 when 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 to https://scixplorer.org.

  • PORT / HOST (HTTP only): where the HTTP transport listens. Default 8000 on 0.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_facets tool

  • Paper 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 export tool's format enum in src/types.ts for the full list

  • Documentation Search: Query SciX help/docs content via the search_docs tool

  • Health Check: Diagnose setup (token, API reachability, tool registry) via the health_check tool

  • Dual 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 Solr fq strings, 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, default score desc), response_format (markdown | json, default markdown).

    • 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 (default author, 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 filter string ready to pass straight back as a search filter_query entry.

    • Available facets, with the Solr field each one counts:

      Facet

      Solr field

      Hierarchical

      author

      author_facet_hier

      yes (2 levels)

      collections

      database

      no

      refereed

      property

      no

      institutions

      aff_facet_hier

      yes (2 levels)

      keywords

      keyword_facet

      no

      publications

      pub_abbrev

      no

      bibgroups

      bibgroup_facet

      no

      simbad

      simbad_object_facet_hier

      yes (2 levels)

      ned

      ned_object_facet_hier

      yes (2 levels)

      award

      grant_facet_hier

      yes (2 levels)

      data

      data_facet

      no

      vizier

      vizier_facet

      no

      pubtype

      doctype_facet_hier

      yes (2 levels)

      planetary

      planetary_feature_facet_hier_3level

      yes (3 levels)

      uat

      uat

      no

      year

      year

      no

    • Hierarchical facet values are prefixed with their level, e.g. 0/Smith, J at the root and 1/Smith, J/Smith, John one level down. Expandable buckets report a child_prefix to pass back as prefix.

  • get_paper: Fetch a paper by bibcode, DOI, arXiv ID, or SciX ID (scix:...) with optional response_format.

  • get_metrics: Metrics for bibcodes (1-2000) with optional response_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); optional rows (1-100, default 20) and response_format.

  • get_references: Backward references for a paper (bibcode, DOI, arXiv ID, or SciX ID); optional rows (1-100, default 20) and response_format.

Export

  • export: Export bibcodes (1-2000) in format — one of the 23 formats in the ExportInputSchema enum in src/types.ts (e.g. bibtex, aastex, endnote, ris, ieee, mnras). Use custom_format with format: custom for 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; optional type (all | owner | collaborator, default all) and response_format.

  • get_library: Metadata + documents for library_id; optional response_format.

  • create_library: Create with name (required), optional description, public (default false), bibcodes, and response_format.

  • delete_library: Permanently delete by library_id; optional response_format.

  • edit_library: Update name, description, or public for library_id; optional response_format.

  • manage_documents: Add/remove documents with library_id, bibcodes (1-2000), action (add | remove), and optional response_format.

  • add_documents_by_query: Add search results to a library with library_id, query, optional rows (1-2000, default 25), and response_format.

  • library_operation: Run set ops on a library with library_id, operation (union | intersection | difference | copy | empty), optional source_library_ids, name/description/public (only for union/intersection/difference, which create a new library), and response_format. For copy, source_library_ids holds the destination library; empty uses none of these.

Permissions & Sharing

  • get_permissions: View owners/collaborators for library_id; optional response_format.

  • update_permissions: Grant, change, or revoke a user's access with library_id, email, permission (read | write | admin | none), and optional response_format. none revokes all access; ownership moves via transfer_library instead.

  • transfer_library: Transfer ownership with library_id, email, and optional response_format.

Annotations

  • get_annotation: Fetch note content for library_id + bibcode; optional response_format.

  • manage_annotation: Add/update note with library_id, bibcode, content, and optional response_format.

  • delete_annotation: Remove note for library_id + bibcode; optional response_format.

Diagnostics

  • health_check: Diagnose the server setup. No required params (optional response_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 is skipped); 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-Limit and X-RateLimit-Remaining response headers are authoritative; a 429 error reports whichever of them the response includes

  • Request higher limits at https://scixplorer.org/feedback/general

SciX Search Syntax

The SciX search supports Solr query syntax:

Syntax

Description

Example

author:"Last, F."

Exact author

author:"Huchra, John"

author:^Last

First author

author:^Smith

title:keyword

Title search

title:exoplanet

abstract:keyword

Abstract search

abstract:"dark matter"

year:YYYY-YYYY

Year range

year:2020-2023

property:refereed

Refereed only

property:refereed

citations(bibcode:X)

Papers citing X

citations(bibcode:2019ApJ...)

references(bibcode:X)

Papers cited by X

references(bibcode:2019ApJ...)

AND, OR, NOT

Boolean operators

black holes AND galaxy

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 build

Local commands

# Watch mode
pnpm dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js

Testing

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:ai

The 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 the test:ai script sets. pnpm test and 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 any scix server 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 tests

Test 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 fq filters, pagination, result limiting, response formatting

  • Facets: Registry/field mapping, json.facet request bodies, hierarchical prefix handling, bucket parsing

  • Paper 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 tools

Example Usage

Search for papers

Use search with query "supernova 2023" to find recent supernova papers

Narrow 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 the Authorization: Bearer header (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 tools
add_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_annotationC
Destructive

Delete an annotation/note for a document in a library.

Inputs: bibcode (required), library_id (required), response_format.

delete_libraryC
Destructive

Delete a library permanently.

Inputs: library_id (required), response_format.

edit_libraryA
DestructiveIdempotent

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.

exportB
Read-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_annotationC
Read-onlyIdempotent

Get annotation/note for a document in a library.

Inputs: bibcode (required), library_id (required), response_format.

get_citationsB
Read-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_facetsA
Read-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_librariesB
Read-onlyIdempotent

Get all libraries for the authenticated user. Can filter by type (all, owner, collaborator).

Inputs: type, response_format.

get_libraryB
Read-onlyIdempotent

Get details about a specific library including metadata and list of documents.

Inputs: library_id (required), response_format.

get_metricsB
Read-onlyIdempotent

Get citation metrics including h-index, citation counts, and paper statistics for a list of bibcodes.

Inputs: bibcodes (required), response_format.

get_paperB
Read-onlyIdempotent

Get detailed information about a specific paper by identifier: bibcode, DOI, arXiv ID, or SciX ID (scix:...).

Inputs: bibcode (required), response_format.

get_permissionsC
Read-onlyIdempotent

Get permission information for a library.

Inputs: library_id (required), response_format.

get_referencesA
Read-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_checkA
Read-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_operationB
Destructive

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_annotationA
DestructiveIdempotent

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_documentsA
DestructiveIdempotent

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.

search_docsA
Read-onlyIdempotent

Search SciX help documentation for information about search syntax, features, API usage, and best practices.

Inputs: query (required), limit.

transfer_libraryA
Destructive

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_permissionsB
DestructiveIdempotent

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

    B3.3/5.0

    Scored across 23 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Provides 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.
      11
      10
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides 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.
      5
      55
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables agents to search, analyze, and explore arXiv academic papers with advanced multi-field search, author lookup, category browsing, citation extraction, and bibliography export.
      46 npm
      Apache 2.0