i-ching

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:

• CLI Tool - Command-line divination and interpretation
• Goose Extension - MCP server for Goose AI assistant
• Claude Code Plugin - Native plugin for Claude Code

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 tool
• i-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

1. Open Goose Desktop

2. Go to Extensions (top-level menu item)

3. Click Add Custom Extension

4. 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

5. Click Save to add the extension

6. Enable the extension by toggling it on in the Extensions list

Using in Goose