Tutorial: Astronomy - Gnist Context

Science

Data source: NASA Planetary Fact Sheet / IAU

Overview

Astronomy wraps NASA Planetary Fact Sheet / IAU, handling authentication, pagination, and rate limits for you. This tutorial covers all 8 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-astronomy": {
      "url": "https://context.gnist.ai/mcp/astronomy/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (8)

`get_planet`

Get detailed information about a solar system planet. Returns mass, radius, orbital parameters, atmosphere composition, and more. Includes the 8 major planets plus Pluto (dwarf planet).

Parameter	Type	Required	Description
`name`	string	required	Planet name (e.g. Earth, Mars, Jupiter, Pluto).

curl -X POST "https://context.gnist.ai/mcp/astronomy/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_planet", "arguments": {"name": "Earth"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/astronomy/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'name': 'Earth'}, 'name': 'get_planet'}},
)
print(resp.json())

`list_planets`

List planets in the solar system. Optionally filter by type: terrestrial (rocky), gas_giant, ice_giant, or dwarf.

Parameter	Type	Required	Description
`planet_type`	any	optional	Filter: terrestrial, gas_giant, ice_giant, dwarf.

curl -X POST "https://context.gnist.ai/mcp/astronomy/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_planets", "arguments": {"planet_type": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/astronomy/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'planet_type': 'example'}, 'name': 'list_planets'}},
)
print(resp.json())

`get_star`

Get detailed information about a notable star. Returns spectral type, magnitude, distance, mass, radius, temperature, and luminosity.

Parameter	Type	Required	Description
`name`	string	required	Star name (e.g. Sirius, Betelgeuse, Polaris, Sun).

curl -X POST "https://context.gnist.ai/mcp/astronomy/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_star", "arguments": {"name": "Sirius"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/astronomy/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'name': 'Sirius'}, 'name': 'get_star'}},
)
print(resp.json())

`search_stars`

Search the star database by name or constellation.

Parameter	Type	Required	Description
`query`	string	required	Search by star name, constellation, or designation.
`limit`	integer	optional	(default: `10`)

curl -X POST "https://context.gnist.ai/mcp/astronomy/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_stars", "arguments": {"query": "renewable energy"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/astronomy/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'renewable energy'}, 'name': 'search_stars'}},
)
print(resp.json())

`list_brightest_stars`

List the brightest stars visible from Earth, sorted by apparent magnitude.

Parameter	Type	Required	Description
`limit`	integer	optional	(default: `10`)

curl -X POST "https://context.gnist.ai/mcp/astronomy/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_brightest_stars", "arguments": {"limit": 10}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/astronomy/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'limit': 10}, 'name': 'list_brightest_stars'}},
)
print(resp.json())

`list_nearest_stars`

List the nearest stars to Earth, sorted by distance in light-years.

Parameter	Type	Required	Description
`limit`	integer	optional	(default: `10`)

curl -X POST "https://context.gnist.ai/mcp/astronomy/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_nearest_stars", "arguments": {"limit": 10}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/astronomy/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'limit': 10}, 'name': 'list_nearest_stars'}},
)
print(resp.json())

`get_constellations`

List all constellations represented in the star database.

curl -X POST "https://context.gnist.ai/mcp/astronomy/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_constellations", "arguments": {}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/astronomy/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'get_constellations'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/astronomy/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/astronomy/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use list_planets to find items, then get_planet to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does Astronomy provide?

Solar system planets and notable stars — mass, radius, orbital parameters, spectral data. It exposes 8 tools: get_planet, list_planets, get_star, search_stars, list_brightest_stars, list_nearest_stars, get_constellations, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Astronomy API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.

Next Steps

Interactive Playground

Try tools in your browser — no setup required.

Full Reference

Complete docs for all 8 tools.

Getting Started with Astronomy