I Ching Divination
An MCP server for I Ching divination (Wilhelm-Baynes translation), compatible with Goose, Claude Code, and other MCP clients, plus a command-line utility.
Screenshots
Claude Sonnet 4
Claude Sonnet 3.5
GPT 4.1
Features
- Three coins method divination following traditional practices
- Wilhelm-Baynes translation with complete hexagram meanings, judgments, and line interpretations
- Multiple interfaces: CLI tool, MCP server for Goose, Claude Code, and other MCP-compatible clients
- Flexible input formats: hexagram numbers, Unicode characters, line numbers, or changing hexagram notation
- Rich output formats: brief, full interpretations, JSON, and MOTD formats
- Changing line support with transformation interpretations
Quick Start
This tool provides three interfaces:
All interfaces use the same binaries. Start with Installation below, then jump to your preferred interface.
Installation
This section covers installing the binaries needed for all interfaces (CLI, Goose, and Claude Code).
Prerequisites
- Rust 1.85.1 or later (for 2024 edition support)
- Cargo (included with Rust)
Installing the Binaries
Option 1: From crates.io (recommended)
cargo install i-ching
Option 2: From source
git clone https://github.com/threemachines/i-ching.git
cd i-ching
cargo install --path .
Option 3: Build without installing (development)
git clone https://github.com/threemachines/i-ching.git
cd i-ching
cargo build --release
Binaries will be in ./target/release/ directory.
Binaries Created
All installation methods create two binaries:
i-ching - CLI tooli-ching-mcp-server - MCP server for Goose and Claude Code
The binaries include embedded data files, so they work anywhere without requiring external data files.
Verify PATH Configuration
Important for MCP usage (Goose & Claude Code): The i-ching-mcp-server binary must be in your PATH.
Check if ~/.cargo/bin is in your PATH:
echo $PATH | grep -q "$HOME/.cargo/bin" && echo "✓ Cargo bin is in PATH" || echo "✗ Cargo bin is NOT in PATH"
If it's not in your PATH, add it to your shell configuration:
# For zsh (macOS default)
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# For bash
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile
Note: If you installed Rust via Homebrew (rather than rustup), cargo install still puts binaries in ~/.cargo/bin, which may not be in your PATH by default.
CLI Usage
Basic Usage
# Random reading using three coins method
i-ching
# Get help
i-ching --help
Input Formats
The CLI supports multiple input formats via the --input flag:
# Hexagram number (1-64)
i-ching --input 1
# Unicode hexagram character
i-ching --input ䷀
# Line numbers (6,7,8,9 format)
i-ching --input "7,8,9,6,7,8"
# Changing hexagram notation
i-ching --input "32→34"
i-ching --input "32->34"
i-ching --input "䷟→䷡"
Output Formats
Control output format with the --format flag:
# Brief format (default for quick reference)
i-ching --format brief --input 1
# Output: ䷀ 1 Initiating
# Full format with complete interpretations
i-ching --format full --input 1
# JSON format for programmatic use
i-ching --format json --input 1
# Numbers only (traditional line values)
i-ching --format numbers --input 1
# Output: [8, 8, 8, 8, 8, 8]
# MOTD format (all caps, for system messages)
i-ching --format motd --input 1
# Output: ䷀ 1 INITIATING
Goose Extension Setup
Prerequisites: Complete Installation above first.
Enable in Goose
-
Open Goose Desktop
-
Go to Extensions (top-level menu item)
-
Click Add Custom Extension
-
Fill in the extension details:
- ID:
i-ching (or your preferred identifier)
- Name:
I Ching Divination
- Description:
I Ching divination readings with Wilhelm-Baynes translation
- Type:
STDIO
- Command:
i-ching-mcp-server
-
Click Save to add the extension
-
Enable the extension by toggling it on in the Extensions list
Using in Goose