AstroMCP

The PyPI package is astro-checker (the name astromcp is too close to an unrelated existing package). The project is still called AstroMCP and both astro-checker and astromcp commands are installed.

An MCP server that gives AI assistants (Claude, Cursor, VS Code, ...) direct, read-only access to public astronomy archives, so you can check a sky position in seconds and answer the first question of any discovery: is it already known?

It queries the Transient Name Server (TNS), SIMBAD, AAVSO VSX, Gaia DR3, ExoFOP-TESS, ALeRCE/ZTF, Fink/Rubin (LSST), IMCCE SkyBoT and several image surveys, and returns compact JSON the model can reason about.

Note: answers depend on third-party services. Archives go down, rate-limit, or lag behind reality (for example, the public TNS archive is refreshed once a day). AstroMCP reports failed sources explicitly instead of pretending nothing is there, but always confirm important results at the source before reporting a discovery.

Tools (14)

Coordinates are ICRS decimal degrees; times are ISO 8601 UTC. Errors come back as {"error": "..."} and, in whats_here, as sources_failed plus a caveat, so a missing archive is never mistaken for "nothing known".

Examples

These are real checks (also in tests/test_integration.py):

"Is there anything known at RA 40.22898, Dec +12.601026?"

whats_here(40.22898, 12.601026)
→ verdict: "known transient"
  evidence: ["TNS: AT 2026agtq at 0.0\"", "ZTF: ZTF26acatcla ndet=10 class=None"]

"What is at the position of TOI-2330?"

whats_here(172.85872, -41.68953)
→ verdict: "known TESS object of interest"
  labels: ["known TESS object of interest", "known variable", "star"]
  evidence: ["SIMBAD: WASP-128 [*] at 0.01\"", "SIMBAD: WASP-128b [BD?] at 0.01\"", "VSX: WASP-128 (EA/BD+ROT) at 0.04\"", ...]

The assistant can then answer: "That's TOI-2330, already known as WASP-128 b, a brown dwarf transiting WASP-128."

An empty patch of sky:

whats_here(200.5, -20.3, 3)
→ verdict: "nothing known", sources_failed: []

"What should I observe tonight from Curitiba?"

observe_tonight(lat=-25.43, lon=-49.27)
→ night_utc: ["2026-10-26T22:27Z", "2026-10-27T07:37Z"], moon illumination 0.99, 33 matching targets
  1. AT 2026afvp  mag 10.3, 8.1 d old, max alt 40.9°, window 03:57–07:37 UTC
  2. AT 2026agsu  mag 17.27, 2.2 d old, max alt 82.8°, window 22:27–02:37 UTC
  ...

observe_tonight selects transients up to 21 days old, TNS discovery mag ≤ 18.5, still unclassified, above 30° while the Sun is below −12° and at least 20° from the Moon (all adjustable). Sun/Moon positions use the Astronomical Almanac low-precision formulas (arcminute level). It is meant to help small telescopes and spectroscopy groups pick classification targets.

Install

Requires Python 3.11+.

uvx astro-checker       # run without installing (recommended; needs uv)
pip install astro-checker  # or install into an environment, then run `astro-checker` (alias: `astromcp`)

Or with Docker (from a clone): docker build -t astromcp . && docker run -i --rm astromcp. See .env.example for the optional variables.

The server speaks MCP over stdio; you normally don't run it by hand, your MCP client launches it.

Configure your MCP client

Claude Code

claude mcp add astromcp -- uvx astro-checker
# with TNS credentials:
claude mcp add astromcp -e TNS_BOT_ID=12345 -e TNS_BOT_NAME=my_bot -e TNS_API_KEY=... -- uvx astro-checker

Add --scope user to make it available in every project.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/; Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "astromcp": {
      "command": "uvx",
      "args": ["astromcp"],
      "env": { "TNS_BOT_ID": "12345", "TNS_BOT_NAME": "my_bot", "TNS_API_KEY": "..." }
    }
  }
}

The env block is optional.

Other clients (Cursor, VS Code, Zed, Continue, ...)

Any client that launches stdio MCP servers works with command uvx and args ["astromcp"], or command astromcp if you installed it with pip. Try it interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector uvx astro-checker

Environment variables

Without TNS credentials, TNS answers come from the daily public objects archive (cached copy or TNS_PUBLIC_CSV); objects reported since 00:00 UTC are missing from it, and whats_here flags this instead of returning a clean "nothing known". The API key is never returned in responses, written to logs, or stored in the cache.

Rate limits and good citizenship

These archives are free public services run by small teams. AstroMCP is built to be polite:

• TNS cone searches are serialized and spaced 6.5 s apart (TNS allows 10 per minute); Retry-After is honored on HTTP 429.
• Every request has a timeout, retries with backoff, and a per-host circuit breaker: when a host fails repeatedly it is skipped for two minutes instead of stalling every query.
• Large tables (ExoFOP TOI/CTOI, TNS public archive) are downloaded once and cached on disk.

Please do the same: don't run whats_here over thousands of positions in a loop (use the archives' bulk services for that), keep your own TNS bot for live queries, and credit the archives in publications (TNS, SIMBAD/CDS, AAVSO VSX, ESA Gaia, ExoFOP-TESS, ALeRCE, Fink, IMCCE, Legacy Survey, Pan-STARRS).

Development

git clone https://github.com/louisperner/AstroMCP && cd AstroMCP
uv sync
uv run pytest                      # offline tests (recorded responses in tests/fixtures)
uv run pytest -m integration       # live queries against the real archives (TNS test needs credentials)
uv run ruff check . && uv run ruff format --check . && uv run mypy --strict

See CONTRIBUTING.md and CHANGELOG.md.

Publishing to the MCP Registry (maintainers)

server.json describes the PyPI package for the official MCP Registry. After the version is on PyPI (the mcp-name comment above must be in the published README):

brew install mcp-publisher        # or download a release binary
mcp-publisher login github        # authenticates the io.github.louisperner namespace
mcp-publisher publish             # reads ./server.json

Bump version in pyproject.toml, src/astromcp/__init__.py and both places in server.json together.

Em português

O AstroMCP é um servidor MCP que dá a assistentes de IA acesso direto (somente leitura) a bases públicas de astronomia — TNS, SIMBAD, VSX, Gaia DR3, ExoFOP-TESS, ALeRCE/ZTF, Fink/Rubin, SkyBoT e cutouts de imagem — para verificar rapidamente se um objeto já é conhecido. Comece por whats_here(ra, dec); para planejar a noite, observe_tonight(lat, lon). Instale com uvx astro-checker ou pip install astro-checker e, no Claude Code, claude mcp add astromcp -- uvx astro-checker. Credenciais do bot do TNS (opcionais) vão nas variáveis TNS_BOT_ID, TNS_BOT_NAME e TNS_API_KEY e nunca aparecem nas respostas. As respostas dependem de serviços externos: confirme na fonte antes de anunciar uma descoberta.

License

MIT © 2026 Louis Perner