i-ching

The I Ching MCP server provides an automated interface for Wilhelm-Baynes I Ching readings that is compatible with MCP clients such as Goose, Claude Code, and other MCP-enabled UIs. It supports the classic three coins divination method and returns both the hexagram data and the full interpretive text. You can access this functionality via the built-in CLI, or remotely through MCP clients by launching the i-ching-mcp-server binary or container and issuing the provided tool calls. The server exposes two primary tools: cast_hexagram to generate a new reading, and interpret_reading to fetch the detailed meaning, judgments, and line interpretations for a given hexagram (including any changing lines). The CLI usage mirrors the MCP endpoints, and the outputs can be delivered in formats suitable for programs (JSON), or for human consumption (brief, full, or MOTD styles).

Prerequisites:

• Rust toolchain (Rust 1.85.1 or later) and Cargo, or an available runtime environment for the chosen distribution method
• Optional: Docker if using the container-based setup

Install options:

Option 1: Build from source (recommended if you want to run the MCP server locally and build the binaries):

# Clone the repository
git clone https://github.com/threemachines/i-ching.git
cd i-ching

# Build the binaries (two will be produced: i-ching and i-ching-mcp-server)
cargo install --path .

Option 2: Install via crates.io (if published there):

cargo install i-ching

Option 3: Run via Docker (containerized approach):

# Pull and run the container (example image name; replace with the official image if provided)
docker run -it threemachines/i-ching-mcp-server

Note: Binaries include embedded data files and do not require external data files at runtime. Ensure the i-ching-mcp-server binary is in your PATH when using Goose or Claude Code integrations.

Verify PATH (for local installs):

echo $PATH | grep -q "$HOME/.cargo/bin" && echo "✓ Cargo bin is in PATH" || echo "✗ Cargo bin is NOT in PATH"

Tips and common issues:

• Ensure the i-ching-mcp-server binary is on your PATH when using MCP clients like Goose or Claude Code.
• For Claude Code, you may need the plugin/config directory present in the repository and the plugin to reference the MCP server binary correctly.
• If you encounter a startup failure in Claude Code (MCP server failed), verify the binary is accessible and the PATH is configured as described in the installation section, and check debug logs for clues.
• The server supports multiple input formats via the CLI: hexagram numbers, Unicode hexagram characters, line lists, and changing-hexagram notation. Use casting with the cast_hexagram tool to generate readings, then interpret_reading for detailed explanations.
• Changing line support is available; when calling interpret_reading, you can provide changing_lines and transformed_hexagram to see how the reading evolves.