Skyportal

Beta: This project is under active development. Bug reports, feature requests, and pull requests are very welcome — please open an issue or submit a PR.

A local MCP (Model Context Protocol) server for SkyPortal and Fritz. It runs on your own machine and exposes SkyPortal data as tools that AI coding assistants — Claude Code, Claude Desktop, Cursor — can call directly. Query astronomical transient data — photometry, spectra, classifications, observability — without leaving your AI assistant.

Compatibility: This has been tested with Claude Code and Claude Desktop. It has not been tested with other MCP-compatible clients (e.g., Cursor, OpenAI Codex, Gemini, or other services) — the setup steps for those clients may differ from the instructions below.

Installation

git clone https://github.com/AnastasiaKWei/skyportal-mcp.git
cd skyportal-mcp
pip install -e .

Configuration

Set two environment variables:

export SKYPORTAL_URL="https://fritz.science"    # Your SkyPortal/Fritz instance
export SKYPORTAL_TOKEN="your-api-token-here"    # From your profile page

For Fritz, get your token at https://fritz.science/profile — click your username, scroll to API Token, and copy it.

Claude Code

Add to your Claude Code MCP config (~/.claude.json):

{
  "mcpServers": {
    "skyportal": {
      "command": "python",
      "args": ["-m", "skyportal_mcp"],
      "env": {
        "SKYPORTAL_URL": "https://fritz.science",
        "SKYPORTAL_TOKEN": "your-token"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "skyportal": {
      "command": "python",
      "args": ["-m", "skyportal_mcp"],
      "env": {
        "SKYPORTAL_URL": "https://fritz.science",
        "SKYPORTAL_TOKEN": "your-token"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "skyportal": {
      "command": "python",
      "args": ["-m", "skyportal_mcp"],
      "env": {
        "SKYPORTAL_URL": "https://fritz.science",
        "SKYPORTAL_TOKEN": "your-token"
      }
    }
  }
}

Available Tools

Read vs Write

• Read — queries data from SkyPortal/Fritz; no data is created or modified.
• Write (SkyPortal) — can create, update, or delete data in your SkyPortal/Fritz account. Use with care; these operations may not be reversible.
• Write (local) — creates files on your local machine (notebooks, CSVs). Does not touch SkyPortal.

Source Data — source_products.py

Tool	Mode	Description
get_source_photometry	Read	Light curve data as CSV (mag or flux format)
get_source_spectra	Read	Spectroscopic observations (summary, CSV, or JSON)
get_source_classifications	Read	Classification history with probabilities
get_source_comments_and_annotations	Read	User comments and ML annotations
get_source_host_galaxy	Read	Host galaxy properties and offset
get_tns_summary	Read	Complete TNS/AstroNote report in one call

Analysis — analysis.py

Tool	Mode	Description
analyze_light_curve	Read / Write (local)	Rise/fade times, peak brightness; notebook mode writes .ipynb + CSV to disk
analyze_color_evolution	Read / Write (local)	Color curves (g-r); notebook mode writes .ipynb + CSV to disk

Observing — observing.py, astro_utils.py

Tool	Mode	Description
get_source_observability	Read	Observing windows from Keck, VLT, Gemini, Palomar, etc.
convert_time	Read	MJD / JD / ISO / Unix time conversion
get_survey_urls	Read	Links to Legacy Survey, PanSTARRS, SDSS, NED, SIMBAD, etc.
search_sources_near_position	Read	Cone search in SkyPortal

Filtering — filtering.py

Tool	Mode	Description
filter_candidates	Read	Search the scanning page for candidates matching criteria
get_candidate_filter_reference	Read	Documentation for available filter parameters
generate_watchlist_filter	Read	Generate MongoDB pipeline JSON for a watchlist (output only, not saved to Fritz)

Bulk Analysis — bulk_analysis.py

Tool	Mode	Description
generate_bulk_lightcurve_code	Write (local)	Writes a Jupyter notebook to ztf_lightcurves/ for bulk ZTF light curve downloads
generate_cone_search_code	Write (local)	Writes code to ztf_cone_search/ for multi-position cone searches
generate_fritz_bulk_query_code	Write (local)	Writes a notebook to fritz_data/ for bulk Fritz photometry/spectra downloads
generate_alert_download_code	Write (local)	Writes a notebook to ztf_alerts/ for downloading ZTF alert packets
generate_field_visualization_code	Write (local)	Writes code to visualize ZTF field and CCD coverage

API Access — api.py

Tool	Mode	Description
call_skyportal_api	Read / ⚠️ Write (SkyPortal)	Direct API calls to any endpoint — POST/PUT/DELETE will modify your SkyPortal account
get_api_quick_reference	Read	API endpoint documentation
get_tools_quick_reference	Read	Tool usage guide

Test Prompts

Try these prompts after connecting to verify the tools work. Replace source names with ones you have access to on your SkyPortal instance.

Source Data

Photometry:

"Get the g and r band photometry for ZTF20acigmel"

Expects: CSV table with MJD, filter, mag, magerr columns. Should return both ztfg and ztfr data points.

Spectra:

"Show me the spectra for ZTF20acigmel"

Expects: Summary listing each spectrum with date, instrument, wavelength range, and a Fritz link.

Classifications:

"What are the classifications for ZTF20acigmel?"

Expects: List of classifications with type (e.g., SN Ia), probability, classifier name, and date.

Comments and annotations:

"Show me the comments and ML annotations for ZTF20acigmel"

Expects: User comments with text/author/date, plus annotation key-value pairs (e.g., braai score, cross-match results).

Host galaxy:

"What is the host galaxy of ZTF20acigmel?"

Expects: Galaxy name, coordinates, redshift, distance, stellar mass, and angular offset from the transient.

TNS summary:

"Generate a TNS report for ZTF20acigmel"

Expects: Formatted report with coordinates (deg + HMS/DMS), discovery info, photometry summary, classification, spectroscopy, and host galaxy — ready to paste into a TNS submission.

Analysis

Light curve analysis (text):

"Analyze the light curve of ZTF20acigmel in g and r bands. Give me a text summary."

Expects: Per-band summary with peak magnitude, peak date, rise time, fade time, and duration.

Light curve analysis (notebook):

"Analyze the light curve of ZTF20acigmel and generate a notebook"

Expects: Creates a Jupyter notebook with interactive Plotly light curve plots and editable analysis code cells.

Color evolution (text):

"What is the g-r color evolution of ZTF20acigmel? Text summary please."

Expects: Color at peak, color trend (bluing/reddening/stable), and a table of color measurements over time.

Observing

Observability:

"When can I observe ZTF20acigmel from Keck and Palomar tonight?"

Expects: Per-telescope observing windows with rise/set times (UTC and local), transit time, peak altitude, and airmass.

Time conversion:

"Convert MJD 60000 to a calendar date"

Expects: All formats — MJD, JD, ISO datetime, and Unix timestamp.

Survey links:

"Get survey links for RA=150.0, Dec=2.0"

Expects: Clickable URLs for Legacy Survey, PanSTARRS, SDSS, NED, SIMBAD, VizieR, WISE, DSS, and others.

Cone search:

"Search for sources within 10 arcsec of RA=150.0, Dec=2.0"

Expects: List of sources sorted by separation, with source ID, coordinates, separation in arcsec, and saved groups.

API Access

Direct API call:

"Use the SkyPortal API to get the source page for ZTF20acigmel"

Expects: Raw JSON response from /api/sources/ZTF20acigmel.

Multi-Tool Prompts

These prompts exercise multiple tools in sequence, testing the AI assistant's ability to chain tool calls.

Photometry + classification + observability:

"Get the photometry and classification for ZTF20acigmel, then check if it's observable from Keck tonight"

Expects: The assistant calls get_source_photometry, get_source_classifications, and get_source_observability (either in parallel or sequentially), then synthesizes the results.

Cone search + photometry:

"Search for sources within 5 arcsec of RA=210.9, Dec=54.3 and get the photometry for any matches"

Expects: First calls search_sources_near_position, then calls get_source_photometry for each result.

TNS report + observability:

"Generate a TNS summary for ZTF20acigmel and tell me when I can observe it from VLT"

Expects: Calls get_tns_summary and get_source_observability (potentially in parallel), then presents both results.

Light curve analysis + color evolution:

"Analyze both the light curve and color evolution of ZTF20acigmel in text format"

Expects: Calls analyze_light_curve and analyze_color_evolution, presenting rise/fade metrics alongside color trend information.

License

BSD 3-Clause