Vedika Astrology and Vastu

@vedika-io/mcp-server

MCP server for the Vedika Intelligence API — astrology, divination and Vastu capabilities across Vedic, Western, KP, Chinese, Tarot, I Ching, Human Design, Numerology, and Ayurvedic domains, exposed as semantic tools for AI agents.

The server calls the documented Vedika API operations. Calculation and interpretation coverage varies by tool and account plan.

Discovery metadata

The server.json descriptor identifies this package as io.github.vedika-io/vedika-mcp-server and uses standard input/output transport. It declares VEDIKA_API_KEY as a required secret environment variable. Supply your key in your MCP client's private environment settings; the descriptor contains no key value.

Quick Start

npm install -g @vedika-io/mcp-server

Get your API key at vedika.io/pricing (starts at $12/mo). No free tier — every query costs money.

Configuration

Where the key goes matters more than which client you use.

• Put it in the gitignored local settings file for your client, never the shared one. A key in a committed config is a key you have published.
• Pin the version. The examples below pin @2.0.9. npx -y @vedika-io/mcp-server with no version resolves whatever npm currently tags latest on every start, so a bad or hijacked release runs the moment it is published, with nothing recording which version you were on.
• Versions before 2.0.4 send your key to whatever VEDIKA_BASE_URL names and follow a redirect while carrying it. Do not pin below 2.0.4.
• The key is a payment credential: every query costs money. Treat it like a card number, not like a setting.

Claude Desktop

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

{
  "mcpServers": {
    "vedika": {
      "command": "npx",
      "args": ["-y", "@vedika-io/mcp-server@2.0.9"],
      "env": {
        "VEDIKA_API_KEY": "vk_live_your_key_here"
      }
    }
  }
}

Claude Code

Add to .claude/settings.local.json:

Not .claude/settings.json. That file is the shared, checked-in one — a key put there is committed, pushed, and in your history for good. settings.local.json is gitignored and stays on your machine. This README said settings.json until 2026-09-07, and the published 2.0.3 package still does.

{
  "mcpServers": {
    "vedika": {
      "command": "npx",
      "args": ["-y", "@vedika-io/mcp-server@2.0.9"],
      "env": {
        "VEDIKA_API_KEY": "vk_live_your_key_here"
      }
    }
  }
}

Cursor

Add to Cursor Settings > MCP Servers:

{
  "vedika": {
    "command": "npx",
    "args": ["-y", "@vedika-io/mcp-server@2.0.9"],
    "env": {
      "VEDIKA_API_KEY": "vk_live_your_key_here"
    }
  }
}

Windsurf

Add to ~/.windsurf/mcp_config.json:

{
  "mcpServers": {
    "vedika": {
      "command": "npx",
      "args": ["-y", "@vedika-io/mcp-server@2.0.9"],
      "env": {
        "VEDIKA_API_KEY": "vk_live_your_key_here"
      }
    }
  }
}

Environment Variables

Tools

Core

Vedic Computation

Western Astrology

Cross-System (3 tools)

Supplementary

Tarot & Divination

Chinese Astrology

Alternative Systems

Vedic Extended

Spiritual & Wellness

Bundles

Utility

Vastu

Input Patterns

Birth Details (required by most Vedic/Western tools)

{
  "datetime": "1990-06-15T14:30:00",
  "latitude": 28.6139,
  "longitude": 77.2090,
  "timezone": "+05:30",
  "ayanamsa": "lahiri"
}

Vedic Compatibility (male/female)

{
  "type": "guna-milan",
  "male": { "datetime": "1992-03-15T10:30:00", "latitude": 28.61, "longitude": 77.20, "timezone": "+05:30" },
  "female": { "datetime": "1994-07-22T08:15:00", "latitude": 19.07, "longitude": 72.87, "timezone": "+05:30" }
}

Western Relationship (person1/person2 -- gender-neutral)

{
  "type": "synastry",
  "person1": { "datetime": "1990-01-15T14:30:00", "latitude": 40.71, "longitude": -74.00, "timezone": "-05:00" },
  "person2": { "datetime": "1992-08-22T09:45:00", "latitude": 34.05, "longitude": -118.24, "timezone": "-08:00" }
}

Location-Only (panchang, muhurta)

{
  "type": "choghadiya",
  "latitude": 28.6139,
  "longitude": 77.2090,
  "timezone": "+05:30"
}

All location fields are optional -- defaults to Delhi (28.6139, 77.2090, +05:30).

Zodiac Signs (predictions, horoscope)

Accepts both English and Hindi (Roman transliteration):

Tarot Spreads

{
  "spread": "celtic-cross",
  "question": "What should I focus on this month?",
  "deck": "rider-waite"
}

Chinese Ba Zi

{
  "datetime": "1990-06-15T14:30:00"
}

Matrimony Match (bride/groom)

{
  "bride": { "datetime": "1994-07-22T08:15:00", "latitude": 19.07, "longitude": 72.87, "timezone": "+05:30", "gender": "female" },
  "groom": { "datetime": "1992-03-15T10:30:00", "latitude": 28.61, "longitude": 77.20, "timezone": "+05:30", "gender": "male" }
}

Output Examples

vedika_birth_chart (type: "kundli")

{
  "ascendant": { "sign": "Virgo", "degree": 14.23, "nakshatra": "Hasta", "pada": 2 },
  "planets": [
    { "name": "Sun", "sign": "Taurus", "house": 9, "degree": 0.85, "nakshatra": "Krittika", "pada": 4, "retrograde": false, "dignity": "Neutral" },
    { "name": "Moon", "sign": "Cancer", "house": 11, "degree": 22.14, "nakshatra": "Ashlesha", "pada": 3, "retrograde": false, "dignity": "Own" },
    { "name": "Mars", "sign": "Pisces", "house": 7, "degree": 6.52, "nakshatra": "Uttara Bhadrapada", "pada": 2, "retrograde": false, "dignity": "Neutral" }
  ],
  "houses": [
    { "house": 1, "sign": "Virgo", "degree": 14.23, "lord": "Mercury" },
    { "house": 2, "sign": "Libra", "degree": 12.15, "lord": "Venus" }
  ]
}

vedika_dasha (system: "vimshottari")

{
  "currentDasha": {
    "mahadasha": { "planet": "Jupiter", "start": "2020-03-15", "end": "2036-03-15" },
    "antardasha": { "planet": "Saturn", "start": "2024-09-01", "end": "2027-03-15" },
    "pratyantar": { "planet": "Mercury", "start": "2025-11-20", "end": "2026-04-30" }
  },
  "dashaTimeline": [
    { "planet": "Ketu", "start": "1990-06-15", "end": "1997-06-15", "years": 7 },
    { "planet": "Venus", "start": "1997-06-15", "end": "2017-06-15", "years": 20 },
    { "planet": "Sun", "start": "2017-06-15", "end": "2023-06-15", "years": 6 }
  ]
}

vedika_tarot_draw (spread: "three-card")

{
  "spread": "three-card",
  "cards": [
    { "position": "past", "card": "The Tower", "number": 16, "suit": "major", "reversed": false, "meaning": "Sudden upheaval, revelation, awakening" },
    { "position": "present", "card": "Two of Cups", "number": 2, "suit": "cups", "reversed": false, "meaning": "Partnership, harmony, mutual attraction" },
    { "position": "future", "card": "The Star", "number": 17, "suit": "major", "reversed": false, "meaning": "Hope, renewal, inspiration, serenity" }
  ],
  "deck": "rider-waite"
}

vedika_chinese_bazi

{
  "system": "chinese",
  "chart": {
    "yearPillar": { "stem": { "name": "Geng", "chinese": "庚", "element": "Metal", "polarity": "Yang" }, "branch": { "name": "Wu", "chinese": "午", "animal": "Horse", "element": "Fire", "polarity": "Yang" }, "label": "Geng Wu" },
    "monthPillar": { "stem": { "name": "Ren", "chinese": "壬", "element": "Water", "polarity": "Yang" }, "branch": { "name": "Wu", "chinese": "午", "animal": "Horse", "element": "Fire", "polarity": "Yang" }, "label": "Ren Wu" },
    "dayPillar": { "stem": { "name": "Xin", "chinese": "辛", "element": "Metal", "polarity": "Yin" }, "branch": { "name": "Hai", "chinese": "亥", "animal": "Pig", "element": "Water", "polarity": "Yin" }, "label": "Xin Hai" },
    "hourPillar": { "stem": { "name": "Yi", "chinese": "乙", "element": "Wood", "polarity": "Yin" }, "branch": { "name": "Wei", "chinese": "未", "animal": "Goat", "element": "Earth", "polarity": "Yin" }, "label": "Yi Wei" },
    "dayMaster": { "name": "Xin", "chinese": "辛", "element": "Metal", "polarity": "Yin" },
    "dominantElement": "Water",
    "elementBalance": { "Wood": 1, "Fire": 2, "Earth": 1, "Metal": 2, "Water": 2 }
  }
}

vedika_compatibility (type: "guna-milan")

{
  "totalScore": 26,
  "maxScore": 36,
  "recommendation": "Good match",
  "factors": [
    { "name": "Varna", "score": 1, "maxScore": 1, "description": "Spiritual compatibility" },
    { "name": "Vashya", "score": 2, "maxScore": 2, "description": "Mutual attraction" },
    { "name": "Tara", "score": 3, "maxScore": 3, "description": "Birth star compatibility" },
    { "name": "Yoni", "score": 3, "maxScore": 4, "description": "Physical compatibility" },
    { "name": "Graha Maitri", "score": 5, "maxScore": 5, "description": "Mental compatibility" },
    { "name": "Gana", "score": 5, "maxScore": 6, "description": "Temperament" },
    { "name": "Bhakoot", "score": 7, "maxScore": 7, "description": "Health & wealth" },
    { "name": "Nadi", "score": 0, "maxScore": 8, "description": "Genetic compatibility" }
  ],
  "mangalDosha": { "male": false, "female": true, "compatible": true }
}

vedika_panchang (element: "full")

{
  "date": "2026-03-13",
  "vara": { "name": "Friday", "deity": "Shukra" },
  "tithi": { "name": "Krishna Chaturdashi", "deity": "Shiva", "endTime": "2026-03-13T18:45:00+05:30" },
  "nakshatra": { "name": "Purva Bhadrapada", "lord": "Jupiter", "endTime": "2026-03-13T22:10:00+05:30" },
  "yoga": { "name": "Siddha", "endTime": "2026-03-13T15:30:00+05:30" },
  "karana": { "name": "Vanija", "endTime": "2026-03-13T18:45:00+05:30" },
  "sunrise": "06:28:00+05:30",
  "sunset": "18:22:00+05:30"
}

vedika_ai_chat

{
  "response": "Based on your birth chart, Jupiter is currently transiting your 7th house...",
  "conversationId": "conv_abc123",
  "tokens": { "input": 1250, "output": 480 },
  "cost": 0.012,
  "system": "vedic"
}

vedika_predictions (period: "daily")

{
  "sign": "aries",
  "period": "daily",
  "date": "2026-03-13",
  "prediction": {
    "overall": "A favorable day for career decisions...",
    "career": "Professional growth opportunities emerge...",
    "love": "Venus influence brings harmony...",
    "health": "Focus on physical activity...",
    "finance": "Avoid impulsive spending..."
  },
  "luckyNumber": 7,
  "luckyColor": "Red"
}

vedika_western_transits (type: "aspects")

{
  "transitAspects": [
    {
      "transitPlanet": "Saturn",
      "transitSign": "Pisces",
      "transitDegree": 22.5,
      "natalPlanet": "Moon",
      "natalSign": "Gemini",
      "natalDegree": 24.1,
      "aspect": "Square",
      "orb": 1.6,
      "applying": true,
      "influence": "challenging"
    }
  ]
}

vedika_usage (action: "wallet")

{
  "walletBalance": 5456,
  "currency": "USD",
  "displayBalance": "$54.56",
  "plan": "professional",
  "subscriptionEndDate": "2026-04-01T00:00:00Z"
}

Note: walletBalance is in USD cents. Divide by 100 to display as dollars.

Error Handling

All errors are returned as MCP tool errors with descriptive messages:

Timeout Configuration

Pricing

No free tier. Every query costs money. Free sandbox with mock data: set VEDIKA_BASE_URL=https://api.vedika.io/sandbox. See also vedika.io/sandbox.

Get your API key at vedika.io/pricing.

Technical Details

• Runtime: Node.js 20+
• Transport: stdio (MCP standard)
• Dependencies: @modelcontextprotocol/sdk, zod (zero other runtime deps)
• HTTP: Native fetch (no axios)
• Idempotency: No idempotency or request-id header is sent unless a tool takes an explicit idempotencyKey (Vastu batch, jobs and vastu_operation). The API reads a caller-sent x-request-id on /v2 as an idempotency claim and refuses it with 422 on endpoints that are not certified for idempotency.
• Retry: One retry with 1s backoff on 5xx for GET requests and for POSTs that carry an idempotencyKey. A billed POST without a key is never retried. 4xx responses, including 402 and 429, are never retried.
• Timeouts: AI chat 90s, POST computation 30s, GET endpoints 15s
• Module format: This package is ESM-only ("type": "module"). Running it via npx/the vedika-mcp-server bin (the normal MCP-client setup above) works regardless of your own project's module format. If you instead import it as a library from a CommonJS project, plain require('@vedika-io/mcp-server') will throw — use a dynamic import instead:

  const { VedikaApiClient } = await import('@vedika-io/mcp-server');

Links

• API Documentation
• API Reference
• Pricing
• Dashboard
• MCP Server Page
• Support

License

MIT

Vastu jobs and artifacts

Call vastu_job_submit with request.operation set to assessments, plan-analyze or plan-report, request.items containing unique {id, input} objects, and a caller-retained idempotencyKey. For a report handoff, use input.format: "html"; JSON reports and plan analyses expose JSON artifacts. Submission returns a stable jobId and maxCharge quote. Each successful item uses the existing single-item price, with no extra job fee; invalid items do not charge.

Use vastu_job_status to poll counts and charges, vastu_job_results to read pages (nextCursor: null ends pagination), and vastu_job_artifact with jobId and itemId to retrieve the exact deliverable and receipt. The same artifact is a read-only resource at vedika://vastu/jobs/{jobId}/items/{itemId}; URL-encode the item ID. Results and artifacts expire after seven days. vastu_job_cancel stops unstarted items; an in-flight item can complete and charge. Use package version 2.0.7 or later for these tools, and confirm that jobs are available on your account. The keyless sandbox returns stateless previews; it cannot retain a job for status or artifact retrieval.