Science MCP

A local Python MCP server for ecosyste.ms Science. It searches software and institutions, resolves identifiers, and reads package metadata, dependencies, archive evidence, and repository relationships through the Science API. Metadata extraction stays in Science.

Run locally

Install Python and uv, then run from this checkout:

uv sync --locked
uv run --locked science-mcp

The server communicates over stdio and waits for an MCP client. Set SCIENCE_API_URL to use another API base, such as a local Science instance. The default is https://science.ecosyste.ms/api/v1.

No local database or catalogue download is required. API lookup and search use Science's /software/lookup and /software/search endpoints; the service operator must deploy these routes and populate the search fields before they can return results. An HTTP 404 from either route means it is unavailable on the configured service.

Related MCP server: Atlas

Tools

Start with lookup_software(query="orbdot") or search_software(query="orbit"), then pass a returned project_id to get_project_context. Use section="packages" or section="direct_dependencies" for details. Follow next_offset with the same section and project.

The additional collection tools return items and next_page. Keep the same filters and per_page when following pages. Detail tools return record, preserving any nested source metadata, alongside the API URL and retrieval time. Bulk project lookup retains unmatched inputs as empty match lists; bulk package lookup returns only unique matches after removing versions and subpaths from PURLs. Neither bulk endpoint creates or syncs records.

Use a package ID from context or bulk lookup to retrieve versions and repositories. A version ID is the local numeric ID from list_package_versions, not the version string. Institution search returns nine-character ROR IDs for get_research_organization; its include_descendants option also applies to paginated sections. Confirmed repository ownership does not establish institutional authorship.

Package repository relationships preserve both direct evidence and connections through shared papers. A shared paper does not establish that a repository publishes the package. Archive observations retain their status and dates; an SWHID alone does not establish archival coverage or verified bytes.

API lookup and search return matching evidence grouped in projects. Preserve those sources and any competing identities. Follow next_after_id using the same query and kind until it is null; the API cursor is a project ID. Names use lowercase Unicode NFC, DOI URLs are accepted, and URL paths retain case. API PURL lookup removes versions and subpaths. Search matches literal substrings without fuzzy matching or confidence scores.

A missing match is not proof that software is absent from Science. Live responses include retrieval time and source timestamps; index updates are asynchronous and pagination can change as metadata changes. Direct dependencies are project-level observations and do not imply that every package published by the project has those dependencies.

Tool pages contain at most 25 matches or items, and seed pages at most 10 projects. Long text and nested arrays have explicit truncations entries. Serialized result data is limited to 64 KiB; a larger result returns an error asking for a smaller page. The API still returns the full search context to the adapter before it selects a page; the newer collection tools request pages from the service. Requests have a 15-second socket timeout and a 10 MiB response limit.

Connect a client

Replace the absolute paths below. Use the full path to uv if the client cannot find it. These commands register the server in the chosen client's configuration.

For Claude Code:

claude mcp add --transport stdio --scope user science \
  -- uv run --directory /absolute/path/to/science-mcp --locked science-mcp

For Codex:

codex mcp add science \
  -- uv run --directory /absolute/path/to/science-mcp --locked science-mcp

Restart the client session, then ask it to look up OrbDot and retrieve its project context. Each client starts its own stdio server process with the same tools.

Optional local snapshot

Set SCIENCE_SEEDS_DB only if you want lookup_software to read a fixed SQLite export instead of the API. Search and context tools still use the live API. There is no published snapshot download yet; creating an export requires a Science checkout with a populated local PostgreSQL database and its Ruby dependencies installed. See Science development setup and the export guide.

From the Science checkout, using its rbenv Ruby installation:

RBENV_VERSION="$(cat .ruby-version)" /opt/homebrew/bin/rbenv exec bundle exec ruby --version
OUTPUT=tmp/search-seeds.sqlite3 RBENV_VERSION="$(cat .ruby-version)" /opt/homebrew/bin/rbenv exec bundle exec rake search_seeds:export

The task prints a JSON summary with the output path and counts. It refuses to overwrite an existing file. Add LIMIT=1000 for a small preview, or omit it for the full eligible catalogue. An empty local Science database produces no useful lookup data; the MCP server does not import the public catalogue into it.

Keep the completed file at a stable path, then verify it from the MCP checkout:

mkdir -p "$HOME/.local/share/science"
cp /absolute/path/to/science/tmp/search-seeds.sqlite3 "$HOME/.local/share/science/search-seeds.sqlite3"
SCIENCE_SEEDS_DB="$HOME/.local/share/science/search-seeds.sqlite3" uv run --locked python scripts/smoke.py

For a client, add --env SCIENCE_SEEDS_DB=/absolute/path/to/search-seeds.sqlite3 before -- in its registration command above and restart the client session. Both schema versions 1 and 2 are supported, and the file is opened read-only. A configured but missing or invalid file returns an error instead of switching sources.

Snapshot lookup returns matches as evidence rows, with a row ID cursor, snapshot ID, completion time, and selection rules. Several rows may describe the same project. Keep the same file throughout pagination; snapshot PURLs must be supplied in canonical versionless form. To refresh, export to a new filename, update the client's configured path, and restart its session. Unset SCIENCE_SEEDS_DB to return to API lookup.

Checks

uv run --locked python -m unittest discover -s tests -v
uv run --locked ruff check src tests scripts
uv run --locked ruff format --check src tests scripts
uv run --locked python scripts/smoke.py
uv run --locked python scripts/smoke.py --extended

The tests start stdio subprocesses and a local HTTP fixture server. CI runs the suite on Python 3.11 through 3.14, with Ruff and zizmor checks. Dependabot checks Python dependencies and GitHub Actions weekly. The smoke script makes read-only requests to the configured Science API and, when configured, queries the local snapshot. --extended also checks identifiers, archive evidence, package APIs, and institutions. The report identifies data-dependent checks that could not run, such as version details when the selected package has no stored versions.

Released under the MIT License.