Tutorial: Horoscopes - Gnist Context

Entertainment

Data source: In-memory curated collection

Overview

Horoscopes wraps In-memory curated collection, handling authentication, pagination, and rate limits for you. This tutorial covers all 7 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-horoscopes": {
      "url": "https://context.gnist.ai/mcp/horoscopes/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (7)

`list_zodiac_signs`

List all 12 zodiac signs with their details. Returns every sign's name, symbol, element, quality, ruling planet, date range, personality traits, and compatible signs.

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

import httpx

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

`get_zodiac_sign`

Get detailed information about a specific zodiac sign. Returns the sign's symbol, element, quality, ruling planet, date range, personality traits, and compatible signs.

Parameter	Type	Required	Description
`name`	string	required	Zodiac sign name (e.g. Aries, Taurus, Gemini). Case-insensitive.

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

import httpx

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

`get_daily_horoscope`

Get the daily horoscope for a zodiac sign. Returns a horoscope reading, lucky number, lucky color, and mood for the day. The reading is deterministic — the same sign and date always produce the same result.

Parameter	Type	Required	Description
`sign`	string	required	Zodiac sign name (e.g. Leo, Scorpio). Case-insensitive.
`date`	any	optional	Date in YYYY-MM-DD format. Defaults to today.

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

import httpx

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

`get_zodiac_sign_by_birthday`

Determine which zodiac sign a person is based on their birthday. Takes a month and day and returns the corresponding zodiac sign with full details.

Parameter	Type	Required	Description
`month`	integer	required	Birth month (1-12).
`day`	integer	required	Birth day (1-31).

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

import httpx

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

`check_zodiac_compatibility`

Check astrological compatibility between two zodiac signs. Returns a compatibility score (0-100) and description based on element pairings and traditional astrological compatibility.

Parameter	Type	Required	Description
`sign1`	string	required	First zodiac sign name. Case-insensitive.
`sign2`	string	required	Second zodiac sign name. Case-insensitive.

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

import httpx

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

`list_astrological_elements`

List the four classical elements used in astrology. The elements are Fire, Earth, Air, and Water. Each zodiac sign belongs to one element.

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

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/horoscopes/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'list_astrological_elements'}},
)
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/horoscopes/" \
  -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/horoscopes/",
    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_zodiac_signs to find items, then get_zodiac_sign to get full details. This two-step pattern is common for exploring data before drilling down.

FAQ

What data does Horoscopes provide?

Zodiac sign information and deterministic daily horoscope readings — sign lookup, birthday-to-sign, compatibility, and daily fortunes. It exposes 7 tools: list_zodiac_signs, get_zodiac_sign, get_daily_horoscope, get_zodiac_sign_by_birthday, check_zodiac_compatibility, list_astrological_elements, 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 Horoscopes 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 7 tools.

Getting Started with Horoscopes