An AI chatbot that gives horoscope readings, draws tarot cards, calculates numerology, interprets dreams, and more — backed by real astronomical calculations via RoxyAPI, not LLM hallucinations. Ships with MCP tool discovery, multi-provider LLM support, and a space-themed UI.
Clone. Add keys. Deploy. Production chatbot in 30 minutes.
Most AI astrology chatbots hallucinate planet positions, make up tarot spreads, and invent numerology results. This one calls RoxyAPI's 110+ verified endpoints via MCP (Model Context Protocol), gets real computed data from astronomical ephemeris engines and mathematical models, then has the LLM interpret it. Every birth chart, every tarot draw, every Life Path calculation is backed by actual computation.
8 domains. Auto-discovered tools via MCP. Multilingual. Any LLM.
| Domain | What You Can Ask |
|---|---|
| Horoscopes | Daily, weekly, monthly horoscopes for all 12 zodiac signs |
| Tarot | Three-card spreads, daily card pull, yes/no oracle |
| Numerology | Life Path number, expression number, compatibility |
| Western Astrology | Natal chart, planetary aspects, moon phases |
| Vedic Astrology | Birth chart (Kundli), Vimshottari Dasha, Gun Milan, Panchang |
| Crystals | Healing properties, chakra associations, gemstone recommendations |
| Angel Numbers | Spiritual meaning of 111, 222, 333, 444, 1111, and more |
| I-Ching & Dreams | Hexagram readings, dream symbol interpretation (2,000+ symbols) |
Responds in the user's language automatically — Hindi, Spanish, French, German, Japanese, and more.
git clone https://github.com/RoxyAPI/astrology-ai-chatbot.git
cd astrology-ai-chatbot
npm install
cp env.example .env.local
# Add your keys to .env.local
npm run devOpen localhost:3000 and start chatting.
You need two keys:
| Key | Where to get it |
|---|---|
| RoxyAPI | roxyapi.com/pricing — powers all readings and calculations |
| LLM | Google, Anthropic, or OpenAI — interprets the data (see below) |
Swap providers with one env var. All three use Vercel AI SDK's unified interface — same code, different model:
| Provider | Env Var | Model | Cost / 1M tokens |
|---|---|---|---|
| Google Gemini (default) | GOOGLE_GENERATIVE_AI_API_KEY |
Gemini 2.0 Flash | $0.10 / $0.40 — has free tier |
| Anthropic | ANTHROPIC_API_KEY |
Claude Haiku 4.5 | $1.00 / $5.00 |
| OpenAI | OPENAI_API_KEY |
GPT-4o Mini | $0.15 / $0.60 |
LLM_PROVIDER=gemini
GOOGLE_GENERATIVE_AI_API_KEY=your_keyUser message → LLM picks a tool → MCP calls RoxyAPI → Real data returned → LLM interprets → Streams to user
- User asks a question ("What does my Saturn placement mean?")
- The LLM selects the right tool from 100+ auto-discovered MCP tools
- RoxyAPI computes the answer from verified astronomical/mathematical engines
- The LLM interprets the structured data into a natural, personalized response
- Response streams back in real-time
No prompt-stuffing. No fake data. No hardcoded horoscopes.
src/
├── app/
│ ├── api/chat/route.ts # Chat endpoint — streamText + MCP tools
│ ├── layout.tsx # Root layout, metadata, JSON-LD SEO
│ ├── page.tsx # Home page with structured data
│ └── globals.css # Space theme, star animations, glass UI
├── components/
│ ├── chat/
│ │ ├── ChatPanel.tsx # Main chat container with useChat
│ │ ├── MessageList.tsx # Messages, empty state, suggestions
│ │ ├── MessageBubble.tsx # User/assistant message rendering
│ │ └── MessageInput.tsx # Input field + send button
│ └── StarField.tsx # Animated star background (CSS)
└── lib/
├── ai.ts # Multi-provider LLM config (Gemini/Claude/GPT)
├── mcp.ts # MCP client — auto-discovers all RoxyAPI tools
└── prompts.ts # System prompt — personality, capabilities, multilingual
Key design decisions:
- MCP over REST — tools are auto-discovered from RoxyAPI's MCP servers. No manual endpoint definitions. Add new tools on the API side and the chatbot picks them up automatically.
- Server-side only — all API keys stay in the Next.js API route. Nothing leaks to the client bundle.
- Model agnostic — Vercel AI SDK v6 abstracts the LLM. Swap Gemini for Claude or GPT with one env var.
- SSR + JSON-LD — structured data and meta tags render server-side for search engine visibility.
| Layer | Tech |
|---|---|
| Framework | Next.js 16 (App Router, React 19) |
| AI | Vercel AI SDK v6 — streaming, tool calling, multi-provider |
| Data | RoxyAPI — 110+ endpoints, 8 domains, native MCP |
| Tool Discovery | MCP via @ai-sdk/mcp — auto-discovers tools at runtime |
| UI | Tailwind CSS v4 + shadcn/ui + custom space theme |
| Types | openapi-typescript — generated from RoxyAPI OpenAPI spec |
| SEO | Server-rendered JSON-LD (schema.org), Open Graph, keyword meta tags |
AI personality — edit src/lib/prompts.ts. Make it mystical, clinical, casual, or match your brand.
Which domains — edit the product list in src/lib/mcp.ts. Comment out products you do not need.
UI theme — components are in src/components/chat/. Star field, colors, and glass effects are in globals.css. Everything is Tailwind — no CSS-in-JS.
API types — run npm run generate:types to regenerate TypeScript types from the latest RoxyAPI OpenAPI spec.
One-click deploy to Vercel:
Or deploy anywhere that runs Node.js:
npm run build && npm start- API keys are server-side only — never exposed to the browser
- All RoxyAPI calls happen in the Next.js API route via MCP, not the client
- LLM provider keys are server-side environment variables
- No secrets in the client bundle
- Input validation via MCP tool schemas
| Resource | URL |
|---|---|
| RoxyAPI Homepage | roxyapi.com |
| API Documentation | roxyapi.com/docs |
| MCP Integration | roxyapi.com/docs/mcp |
| Pricing | roxyapi.com/pricing |
| All Products | roxyapi.com/products |
| Starter Apps | roxyapi.com/starters |
Built with RoxyAPI — the data engine behind real astrology, tarot, and numerology calculations.