Yarrow
I-Ching (周易) oracle: cast a hexagram, read classical commentary, get a reflection. Bilingual.
Install Yarrow
Pick your client, then add it in one click or paste the config.
~/Library/Application Support/Claude/claude_desktop_config.json{
"mcpServers": {
"yarrow": {
"command": "npx",
"args": [
"-y",
"@shaozhengkun/yarrow-mcp"
]
}
}
}
Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.
Clients with native remote MCP support can connect directly to this URL.
https://yarrow-oracle.shaozhengkun.workers.dev/mcp
Automated check passed— started and listed 7 tools correctly (5d ago).
Overview
Tools7
What Yarrow lets your agent do. Expand a tool for its parameters.
Security & health
What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.
Recent health check succeeded.
What it can do
From the 7 tools this server returned when we ran it.
Observed 2026-10-30 in an isolated sandbox. A description of reach, not a security audit.
Supply-chain signal
No high-severity advisories surfaced by our automated scan.
Scanned 5d ago via OSV.dev · @shaozhengkun/yarrow-mcp (npm)
Adoption & maintenance
Factual signals from GitHub, npm, and our automated checks — not a rating.
From the project README
Yarrow — An I-Ching oracle for the agent era
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
| Path | What |
|---|---|
src/ | Cloudflare Workers source — public MCP endpoint + iOS app proxy |
src/data_hexagrams.json | 64 hexagrams with bilingual classical sources (杨天才 / 朱熹 / 断易天机 / 白话题解) |
src/hexagram.ts | Deterministic casting (coins / yarrow stalks / random), seeded by FNV-1a + mulberry32 |
src/mcp.ts | MCP JSON-RPC 2.0 handler (3 tools, 30 readings/day per anonymous caller) |
.claude-plugin/marketplace.json | Claude Code / Codex plugin marketplace manifest |
skills/yarrow/SKILL.md | The 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.md | Copy-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:
claude plugin marketplace add https://github.com/shaozhengkun123/yarrow
claude plugin install yarrow
Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"yarrow": { "url": "https://yarrow-oracle.shaozhengkun.workers.dev/mcp" }
}
}
Codex CLI / Hermes / older Claude Desktop — use the stdio bridge:
npx @shaozhengkun/yarrow-mcp
Or pin it in your client's config — see INTEGRATIONS.md for every platform.
Anyone with curl —
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
| Tool | Purpose |
|---|---|
cast_hexagram | Toss the coins / cast the stalks. Returns primary hexagram + moving lines + changing hexagram, all metadata. Deterministic if you pass seed. |
lookup_hexagram | Get a hexagram's classical text — Wilhelm-style header, judgment, image, and 杨天才 / 朱熹 / 断易天机 / 白话 commentaries. |
divine | One-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.
git clone https://github.com/shaozhengkun123/yarrow
cd yarrow
npm install
npx wrangler login
npx wrangler kv:namespace create QUOTA # copy id into wrangler.toml
echo -n '<your OpenAI-compatible chat URL>' | npx wrangler secret put PROXY_URL
echo -n '<your API key>' | npx wrangler secret put PROXY_KEY
npx 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.
Reviews
No reviews yet — be the first to share how it worked for you.
Frequently Asked Questions about Yarrow
Related MCP servers
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.
AllMCPs Directory Badge
Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.
[](https://allmcps.com/mcp/yarrow)<a href="https://allmcps.com/mcp/yarrow"><img src="https://allmcps.com/api/badge/yarrow?style=directory" alt="Yarrow on AllMCPs" /></a>