Yarrow

io.github.shaozhengkun123Published by GitHub account shaozhengkun123v0.1.0Updated Oct 24, 2026

I-Ching (周易) oracle: cast a hexagram, read classical commentary, get a reflection. Bilingual.

VerifiedStreamable HTTPWeb executable

Overview

AI-generated overview

Yarrow is a remote I-Ching and tarot oracle that lets an assistant cast hexagrams, look up classical commentary, and get source-grounded reflections.

What you can do
  • Cast hexagrams with moving lines and a changing hexagram, optionally seeded for repeatable results
  • Look up a hexagram's classical sources: judgment, image, Tuan commentary, Zhu Xi, Yang Tiancai and anecdote, in Chinese and English
  • Look up the Yilin verse for one hexagram changing into another
  • Draw a single upright Waite-Smith Major Arcana card with a Waite source excerpt
  • Get a one-shot reading that casts, cites the sources first, then offers a reflection
  • Combine an I-Ching cast and a tarot card into a two-lens reading with shared themes and a next step
When to use it
Useful when you want symbolic reflection or a structured prompt for thinking through a decision, with classical texts quoted rather than invented. Suited to personal reflection and journaling-style conversations, not to factual prediction.
Requirements
A remote streamable HTTP endpoint; no account, API key or headers are declared. A stdio bridge package is mentioned for clients that do not speak HTTP MCP. Network access is required.
Before you install
Readings are framed as reflection, not prediction, and the server says it refuses fortune-telling, medical, legal or financial advice. The public endpoint is rate-limited to 30 readings per day per anonymous caller. Questions you send go to a third-party hosted service.

Installation

In SourceWeft

  1. Open Yarrow in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.shaozhengkun123%2Fyarrow/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "yarrow": {
      "type": "http",
      "url": "https://yarrow-oracle.shaozhengkun.workers.dev/mcp"
    }
  }
}

README

Yarrow — An I-Ching oracle for the agent era

[App Store] [MCP] [License: MIT]

Yarrow lets you (and your agents) consult the Book of Changes — cast a hexagram, read the classical sources, and get a Wilhelm/Baynes-style reflection. Offline-first iOS app, plus a public MCP server so any LLM agent can reach the same oracle.

"The I-Ching does not predict; it mirrors. The question you bring decides the reading."

What's in this repo

PathWhat
src/Cloudflare Workers source — public MCP endpoint + iOS app proxy
src/data_hexagrams.json64 hexagrams with bilingual classical sources (杨天才 / 朱熹 / 断易天机 / 白话题解)
src/hexagram.tsDeterministic casting (coins / yarrow stalks / random), seeded by FNV-1a + mulberry32
src/mcp.tsMCP JSON-RPC 2.0 handler (3 tools, 30 readings/day per anonymous caller)
.claude-plugin/marketplace.jsonClaude Code / Codex plugin marketplace manifest
skills/yarrow/SKILL.mdThe Yarrow skill — pluggable into any Claude Code or Codex install
npm/yarrow-mcp/@shaozhengkun/yarrow-mcp — stdio bridge for clients that don't speak HTTP MCP
submissions/Drafts for modelcontextprotocol/servers, Smithery, mcp.run
INTEGRATIONS.mdCopy-paste configs for Claude Code / Claude Desktop / Codex / Hermes

The iOS source lives separately at yarrow-ios (TODO).

For users

📱 iOS app

Download on the App Store → · $4.99 · iOS 17+ · no tracking, no account.

All 64 hexagrams and their classical commentary ship in the app; AI reading is optional and runs through this Worker.

🤖 Agents

Claude Code — install the plugin:

bash
claude plugin marketplace add https://github.com/shaozhengkun123/yarrowclaude plugin install yarrow

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

json
{  "mcpServers": {    "yarrow": { "url": "https://yarrow-oracle.shaozhengkun.workers.dev/mcp" }  }}

Codex CLI / Hermes / older Claude Desktop — use the stdio bridge:

bash
npx @shaozhengkun/yarrow-mcp

Or pin it in your client's config — see INTEGRATIONS.md for every platform.

Anyone with curl —

bash
curl -s -X POST https://yarrow-oracle.shaozhengkun.workers.dev/mcp \  -H 'Content-Type: application/json' \  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{    "name":"divine",    "arguments":{"question":"Should I take the new job?","locale":"en"}  }}'

The MCP tools

ToolPurpose
cast_hexagramToss the coins / cast the stalks. Returns primary hexagram + moving lines + changing hexagram, all metadata. Deterministic if you pass seed.
lookup_hexagramGet a hexagram's classical text — Wilhelm-style header, judgment, image, and 杨天才 / 朱熹 / 断易天机 / 白话 commentaries.
divineOne-shot reading: casts, looks up, and generates a Wilhelm/Baynes-style reflection grounded in the sources. 30/day per anonymous caller.

Self-hosting

This Worker is MIT — fork, deploy your own, point your agents at your URL.

bash
git clone https://github.com/shaozhengkun123/yarrowcd yarrownpm installnpx wrangler loginnpx wrangler kv:namespace create QUOTA          # copy id into wrangler.tomlecho -n '<your OpenAI-compatible chat URL>' | npx wrangler secret put PROXY_URLecho -n '<your API key>'                   | npx wrangler secret put PROXY_KEYnpx wrangler deploy

Your endpoint will be https://yarrow-oracle.<your-subdomain>.workers.dev.

Boundaries

Yarrow is for reflection, not prediction. The system prompt baked into the Worker refuses:

  • fortune-telling / specific future predictions
  • medical, legal, or financial advice
  • requests to "reveal what will happen"

The classical voice is direct; the framing is Jungian. This is the line we draw, in the iOS app and the MCP both.

License

MIT for code; classical sources are in the public domain. See LICENSE.

Source: README.md at commit 506657f

Tools

7

cast_hexagram

Cast a hexagram for an I-Ching consultation. Returns the primary hexagram, the six lines (6=old yin, 7=young yang, 8=young yin, 9=old yang from bottom to top), any moving lines, and the changing hexagram if there are moving lines. Pass `seed` to make the cast deterministic (useful for testing or for reproducing a reading).

Parametersseedmethodquestion

lookup_hexagram

Return the full classical sources for a hexagram by its number (1–64): judgment (卦辞), image (大象), Tuan commentary, Zhu Xi 周易本义, Yang Tian Cai modern explanation, Yarrow's separately labelled Chinese reading aid, and historical anecdote — with available Chinese and English source material.

Parameterslocalenumberrequiredcompact

lookup_yilin

Look up the 焦氏易林 verse for a primary hexagram changing into another hexagram. This is a local classical-source lookup, not an AI reading.

Parametersprimary_numberrequiredchanging_numberrequired

cast_tarot

Draw one upright Major Arcana card for reflection. Uses a deterministic one-card Waite-Smith Major Arcana method and returns a selected source excerpt from Arthur Edward Waite's public-domain 1910/1922 text. Pass `seed` to reproduce the same draw.

Parametersseedquestion

divine

Ask the I Ching. See your next step. Cast a hexagram, show the classical sources first, then offer a thoughtful reflection grounded in those sources. Sources first. Reflection, not prediction. The divine name remains stable for oracle/divination client compatibility. Supports English, Chinese, Japanese, Korean, Spanish, French, German, Portuguese, Italian, Russian, Arabic, Hindi, Indonesian, and English+Chinese bilingual output. Daily quota: 30 completed readings per device_id (or per anonymous IP if no device_id is supplied); timeout, provider failure, incomplete response, and cancellation do not consume it.

Parametersseedlocalemethodquestionrequireddevice_id

tarot_reading

Ask one real question through a single upright Waite-Smith Major Arcana card. Returns a direct calibrated answer first, the named card and bound Arthur Edward Waite 1910 source excerpt, a practical reality check, and one observable next step. No reversals, astrology, redraw loop, or guaranteed prediction. Daily quota is shared with completed divine and Two Lenses readings.

Parametersseedlocalequestionrequireddevice_id

two_lenses

Bring one real question to two independent symbolic traditions: a source-first I-Ching cast and one upright Waite-Smith Major Arcana card. Returns a clear calibrated answer first, then five grounded sections covering the I Ching lens, Tarot lens, shared themes, different emphasis, and next step. Direction without guaranteed prediction or mutual-confirmation claims. Daily quota is shared with completed divine readings.

Parameterslocalemethodquestionrequireddevice_idtarot_seediching_seed

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.