Log inSubmit server
Oraclebone logo

Oraclebone

Runs audited tarot, I Ching, Xiao Liu Ren, and Bazi tools through a local MCP server.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Oraclebone

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "oraclebone": {
      "command": "uvx",
      "args": [
        "oraclebone"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

uvx oraclebone

Process exited before answering initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 9d ago.

Overview

The Oraclebone MCP server gives AI agents audited tools for tarot, I Ching, Xiao Liu Ren, and Bazi readings. Local scripts generate the cards, hexagrams, positions, or Four Pillars data, while the model interprets the returned result instead of creating it. It exposes five MCP tools and returns JSON with method metadata for review and testing. Reach for it when an agent needs reproducible or auditable symbolic readings with explicit boundaries around randomness and interpretation.

Use cases

  • Draw tarot cards for reflective agent workflows
  • Cast I Ching hexagrams with coin or yarrow methods
  • Generate Xiao Liu Ren results from numbers or time
  • Create Bazi charts from Gregorian birth datetimes
  • Test symbolic-reading workflows with seeded JSON output

Key features

  • Five MCP tools for four divination systems and interpretation templates
  • Local audited scripts generate results before model interpretation
  • JSON output with method metadata
  • System randomness by default with optional seeded runs
  • CLI, Python API, and standalone skill-folder workflows
  • Optional Bazi support through lunar-python

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

10/10 checks healthy over the last 57d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 5d ago via OSV.dev · oraclebone (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars6Stargazers on the source repository.
Last commit2mo agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.

How Oraclebone works

What the Oraclebone MCP server does

The Oraclebone MCP server provides a local MCP interface for four symbolic systems: tarot, I Ching, Xiao Liu Ren, and Bazi, also called Four Pillars. It is intended for reflection and symbolic reasoning rather than deterministic prediction. The server separates result generation from interpretation: audited local scripts perform the draw or cast, and the connected model works from that output.

Five MCP tools are included:

  • tarot_draw draws cards using supported decks, spreads, and reversal settings.
  • iching_cast produces a six-line hexagram, including primary and resulting hexagrams where applicable.
  • xiaoliuren_cast casts from lunar-style numbers or a Gregorian-time fallback.
  • bazi_cast creates a Bazi chart from a Gregorian birth datetime.
  • interpretation_template returns a structured template for agent interpretation.

How it works

The Oraclebone MCP server runs the underlying audited scripts locally and exposes their results to an MCP host. Normal operation uses system randomness. A seed can be supplied for tests and repeatable demonstrations, but seeded output is not presented as the default for real readings.

The scripts emit JSON containing enough information to inspect the method used. Traditional methods and their boundaries are documented by skill. Where an approximate method is available, the output includes a warning rather than representing it as traditional. This design prevents the model from silently inventing a card draw, hexagram, or other divination result.

The package also exposes a command-line interface named ai-divination and Python modules for direct use. The MCP layer is useful when an agent host should select and call the operation, while the CLI and Python API support scripts, tests, and workflows outside MCP.

Setup and configuration

Install the package from PyPI with pip install oraclebone. The repository also supports installation from a checkout or editable installation during development. The MCP executable shipped by the package is ai-divination-mcp; configure that executable in an MCP-compatible host after installing the package.

The project documents use with Claude Desktop, Codex, Continue, and Cursor. It also provides agent-skill adapters for OpenAI/Codex, Claude Desktop or claude.ai project skills, Gemini CLI, and Cursor. These adapters route requests through the same ai-divination commands.

Bazi requires the optional lunar-python dependency. If only tarot, I Ching, or Xiao Liu Ren is needed, the other skills can be installed or copied independently. The shell installer targets ~/.claude/skills by default; set AI_SKILLS_DIR to select another agent skill directory.

Tools and capabilities

Tarot supports named decks and spreads, including major-arcana and three-card examples, with optional reversals. I Ching supports coin and yarrow methods. Xiao Liu Ren accepts number-based inputs and can use Gregorian time as a fallback. Each skill can be invoked through MCP, the CLI, or its underlying Python script, and the scripts return JSON.

The package can also install self-contained skill folders containing instructions, host metadata, scripts, and references. This is separate from using the MCP server, but it allows an agent to use the same audited operations through a skill workflow.

Limitations and notes

Oraclebone does not establish scientific evidence for divination efficacy. Its value is procedural: it records how a symbolic result was generated and keeps interpretation distinct from generation. A seeded result is intended for reproducible demos and tests, not as a replacement for normal randomness.

Bazi is not available from the base installation unless the optional lunar-python extra is installed. The server is local and depends on the MCP host being able to launch the installed executable. The project does not claim that model interpretations are objective predictions; the model still supplies the interpretation after receiving the generated data.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Oraclebone

Oraclebone is an MCP server that connects AI agents to local audited divination scripts for tarot, I Ching, Xiao Liu Ren, and Bazi. Its main tools are tarot_draw, iching_cast, xiaoliuren_cast, bazi_cast, and interpretation_template. The server generates results first, so the model interprets supplied data rather than inventing a draw.

Install it with `pip install oraclebone`, then configure the packaged `ai-divination-mcp` executable in your MCP host. Installation from a checkout and editable installation are also supported. Bazi additionally requires the optional `lunar-python` dependency.

Yes, Oraclebone works with Cursor through its MCP server and also includes a Cursor skill adapter. The Cursor adapter routes through the audited `ai-divination` CLI and includes a guard against inventing the draw.

Yes, Oraclebone supports seeded runs for reproducible tests and demonstrations. Normal readings use system randomness by default, while seeded output is intended for testing and repeatable examples rather than as the standard mode for real readings.

Related MCP servers

All in Spirituality & Esoterica All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewOraclebone AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/oraclebone?style=directory)](https://allmcps.com/mcp/oraclebone)
HTML Embed
<a href="https://allmcps.com/mcp/oraclebone"><img src="https://allmcps.com/api/badge/oraclebone?style=directory" alt="Oraclebone on AllMCPs" /></a>