This server provides MCP tools for I Ching divination and bibliomantic consultations, integrating traditional Chinese wisdom with AI. You can:
Perform I Ching divination (i_ching_divination) using a simulated three-coin method with cryptographically secure randomness, optionally tied to a query, returning hexagrams, changing lines, and guidance.
Run a full bibliomantic consultation (bibliomantic_consultation) that augments your question with I Ching wisdom, following Philip K. Dick's The Man in the High Castle, useful for reflective decision-making.
Look up any of the 64 hexagrams (get_hexagram_details) by number, including traditional Chinese names, Unicode symbols, and philosophical commentary.
View server statistics (server_statistics) for system information and capabilities.
Access resources directly: individual hexagrams via hexagram://{number} and the full database via iching://database.
Use structured prompt templates for career guidance, creative projects, and general life advice.
Explore I Ching philosophy, ancient Chinese wisdom traditions, and literary context, or use it for creative writing inspiration, philosophical reflection, and educational purposes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Bibliomantic MCP Server perform an I Ching divination for guidance on my career decision"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Tired of watching your LLM queries wander down the wrong path because of random hallucinations?
Why leave the randomness entirely to the model?
bibliomantic-mcp-server gives an LLM a different source of uncertainty: randomly selected context drawn from the I Ching.
The inspiration comes from Philip K. Dick's science-fiction novel The Man in the High Castle. Throughout the novel, characters consult the I Ching when making decisions. Its influence extends beyond the characters themselves: the oracle affects the direction of the story, the fictional book within the story, and—famously—the process Philip K. Dick used while writing the novel.
This MCP server applies that idea to an LLM.
Rather than asking the model to simply invent another direction when reasoning or writing reaches an uncertain point, the user can explicitly invoke the server to introduce an I Ching consultation into the model's context. The resulting hexagram becomes an external, stochastic influence that the LLM can interpret and incorporate into whatever it is doing.
In other words:
If your LLM is going to hallucinate anyway, you might as well give its hallucinations some ancient Chinese wisdom to work with.
The server operates only when invoked by the end user or an MCP client acting on the user's request. It is not intended to autonomously interfere with ordinary model responses.
And, importantly, this project does not claim that the I Ching predicts the future or provides reliable real-world advice. It is an experimental, literary, philosophical, and creative-writing tool—particularly suitable for anyone curious about what happens when an AI system is allowed to wander through the same sort of bibliomantic machinery that helped shape a Philip K. Dick novel.
bibliomantic-mcp-server is a Model Context Protocol server that allows an MCP-compatible AI application to consult the I Ching.
It provides:
Traditional 64-hexagram I Ching data
Three-coin divination simulation
Randomized bibliomantic context for LLM reasoning and writing
Individual hexagram lookup
MCP resources containing hexagram data
Structured consultation tools designed for AI use
The interesting part is not merely generating a hexagram.
The interesting part is putting that hexagram inside an LLM's context and seeing what the model does with it.
Related MCP server: taibu
Large language models are probabilistic systems. When confronted with ambiguity, incomplete information, creative choices, or multiple plausible reasoning paths, they must choose among possibilities.
Normally, those choices emerge entirely from the model itself.
Bibliomantic MCP introduces an additional influence.
User question
│
▼
LLM
│
│ user requests bibliomantic consultation
▼
bibliomantic-mcp-server
│
▼
three-coin I Ching simulation
│
▼
hexagram + interpretation
│
▼
added to LLM context
│
▼
LLM continues with a new influenceThe oracle does not replace the model's reasoning.
It perturbs it.
That makes the server potentially interesting for:
creative writing
speculative reasoning
brainstorming
narrative generation
alternative perspectives
experiments involving stochastic AI behavior
literary experiments inspired by Philip K. Dick
The central inspiration for this project is Philip K. Dick's The Man in the High Castle.
The I Ching occupies an unusual position in the novel. Characters repeatedly consult it when deciding what to do, allowing apparently random divinations to alter their actions and therefore the course of the story.
The idea becomes recursive.
The novel contains a fictional novel, The Grasshopper Lies Heavy, whose existence influences the characters living inside Dick's alternate history. Meanwhile, Dick himself used the I Ching while writing The Man in the High Castle.
The result is an unusual feedback loop between:
author
oracle
story
characters
story-within-the-story
bibliomantic-mcp-server explores what happens when an LLM is inserted into that loop.
Instead of:
Author → I Ching → Storywe can now experiment with:
Human → LLM → I Ching → LLM → StoryThe term hallucination is used somewhat playfully here.
This server does not technically prevent LLM hallucinations, improve factual accuracy, or make unreliable model output trustworthy.
In fact, its purpose is almost the opposite.
Bibliomantic MCP deliberately introduces an external, randomly selected conceptual influence when the user asks for one.
For factual questions, this may be completely inappropriate.
For fiction, brainstorming, speculative thinking, and experiments in AI creativity, however, deliberately steering the model toward an unexpected conceptual path can be the entire point.
i_ching_divinationPerforms an I Ching divination using a simulated traditional three-coin method and returns the resulting hexagram and interpretation.
bibliomantic_consultationPerforms a complete bibliomantic consultation intended to provide additional context for an LLM responding to a particular question or creative problem.
get_hexagram_detailsRetrieves information about a particular I Ching hexagram by number.
1–64server_statisticsReturns information about the server and its available capabilities.
hexagram://{number}Loads a particular hexagram as an MCP resource.
For example:
hexagram://1iching://databaseProvides access to the complete 64-hexagram database.
The server includes structured prompt templates for several forms of consultation:
career_guidance_prompt
creative_guidance_prompt
general_guidance_prompt
These templates provide examples of how an MCP client can incorporate bibliomantic context into a larger conversation.
They should not be interpreted as endorsements of the I Ching as a source of professional or real-world advice.
Python 3.10+
An MCP-compatible host
Clone the repository:
git clone https://github.com/d4nshields/bibliomantic-mcp-server.git
cd bibliomantic-mcp-server
pip install -e .An MCP configuration can then launch the server with Python:
{
"mcpServers": {
"bibliomantic": {
"command": "python",
"args": ["-m", "bibliomantic_server"]
}
}
}Ask your MCP-enabled AI:
I'm stuck on what should happen next in this story. Consult the I Ching and use the result as an influence on the next scene.
There are several plausible ways to approach this fictional problem. Perform a bibliomantic consultation and use the result to choose an unexpected direction to explore.
Consult the I Ching using the bibliomantic server. Treat the result as an external influence on the direction of this science-fiction story.
Perform an I Ching divination and explain the resulting hexagram.
Tell me about I Ching hexagram 42.
The server simulates the traditional three-coin method.
Coin tosses generate the six lines forming an I Ching hexagram. The resulting pattern identifies one of the 64 hexagrams available to the model.
Randomness is generated using Python's secrets module.
The important distinction is that the random result is generated outside the LLM.
That means the model does not get to quietly choose the supposedly "random" piece of wisdom that happens to fit the answer it was already constructing.
The MCP server chooses first.
The LLM has to deal with what it gets.
That constraint is a significant part of the experiment.
An LLM asked to "pick something random" is still generating tokens according to its learned probability distribution.
Bibliomantic MCP instead introduces a result produced outside the model.
This creates a simple form of stochastic context injection:
LLM state
+
externally generated random event
+
structured I Ching interpretation
=
new model contextThe result can push a conversation toward concepts or associations that might otherwise have had very low probability of appearing.
For creative applications, that can be useful.
Or at least interesting.
Bibliomantic consultation is intended to be explicitly invoked.
The server does not need to participate in every query and should not silently inject divinations into unrelated conversations.
A user might work normally with an LLM for an extended period and invoke the oracle only when they want:
an unexpected direction
a narrative disruption
an alternative interpretation
a creative constraint
a deliberate random influence
This keeps the oracle in approximately the role it occupies in The Man in the High Castle: something consulted when a character—or in this case, a user—decides to consult it.
Good uses include:
Science-fiction writing
Philip K. Dick-inspired literary experiments
Plot generation
Character decisions
World-building
Creative brainstorming
Perspective shifting
Generative-art experiments
Studying human/AI interaction with random external context
Demonstrating MCP tools and resources
Do not treat output from this server as authoritative guidance for:
medical decisions
legal decisions
financial decisions
personal safety
mental-health treatment
major life decisions
predictions of future events
The server does not establish that divination works, that an oracle possesses knowledge, or that randomly selected philosophical text provides factual evidence.
This is an experimental creative tool, not an oracle you should bet your life on.
If Philip K. Dick-style weirdness emerges from your LLM session, however, the software is probably working as intended.
The project uses:
Python
FastMCP
Model Context Protocol
A complete 64-hexagram data set
Python's secrets module for external randomness
Type hints and generated schemas
MCP tools, resources, and prompts
The server requires no external API to perform a consultation.
python bibliomantic_server.pymcp dev bibliomantic_server.pyThe server is deliberately simple.
No persistent user tracking
No requirement to transmit consultations to an external divination service
No external API dependency for generating random results
Input validation for server parameters
Randomness generated locally
Consultation occurs only when invoked
As with any MCP server, users should review the source code and understand the permissions granted to an MCP server before enabling it in an AI host.
Contributions are welcome.
When contributing:
Follow the existing code style.
Preserve compatibility with MCP clients.
Add or update tests when changing behavior.
Update documentation when adding tools or resources.
Preserve the distinction between creative bibliomancy and factual or professional advice.
Keep the weird part weird.
MIT License. See LICENSE for details.
This project owes its existence to an unusual chain of ideas:
the ancient Chinese I Ching
centuries of bibliomantic practice
Philip K. Dick
The Man in the High Castle
modern large language models
Model Context Protocol
and the questionable but irresistible idea that an AI's random wanderings might benefit from consulting a 3,000-year-old book first.
The model was going to take some path.
Now the oracle gets a vote.
Enhanced bibliomantic consultation with full traditional I Ching elements. DRAMATICALLY IMPROVED CONTENT while maintaining exact interface compatibility.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'enhanced content' and 'maintaining exact interface compatibility' which gives some implementation context, but doesn't describe what the tool actually does behaviorally - whether it performs calculations, returns interpretations, requires authentication, has rate limits, or what 'consultation' entails. The description is too vague about the actual operation and output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (two sentences) and doesn't waste words, but it's not effectively structured. The first sentence is somewhat informative while the second is technical implementation detail that doesn't help an AI agent understand when or how to use the tool. While concise, it's not optimally front-loaded with the most important information for tool selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which reduces the need to describe return values) and only one parameter, the description is somewhat complete but inadequate. It mentions 'enhanced' and 'traditional I Ching elements' which provides some context, but doesn't explain what makes it different from i_ching_divination or what 'consultation' means. For a single-parameter tool with output schema, more could be done to explain the tool's unique value and use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 1 parameter (query) with 0% description coverage in the schema itself. The tool description provides no information about what the 'query' parameter should contain, its format, or examples of valid inputs. For a single parameter tool with zero schema documentation, the description should compensate by explaining the parameter's purpose and expected content, which it fails to do.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Enhanced bibliomantic consultation with full traditional I Ching elements' which provides some purpose context, but it's vague about what the tool actually does. It doesn't specify the action (consult? analyze? interpret?) or what resource it operates on. The second sentence about 'maintaining exact interface compatibility' is technical rather than functional. This is better than a tautology but lacks the specific verb+resource clarity needed for high scores.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There are no explicit guidelines about when to use this tool versus the sibling tools (get_hexagram_details, i_ching_divination, server_statistics). The description mentions 'enhanced' and 'full traditional I Ching elements' which might imply this is a more comprehensive option than i_ching_divination, but this is only implied rather than stated. No explicit when/when-not guidance or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enhanced hexagram details with traditional Chinese names, Unicode symbols, and rich commentary. MAINTAINS BACKWARD COMPATIBILITY while dramatically improving content quality.
| Name | Required | Description | Default |
|---|---|---|---|
| hexagram_number | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'enhanced' details and 'improving content quality,' which suggests this might return more or better data than a basic version, but doesn't specify what that entails (e.g., format, structure, or performance). It also doesn't cover critical aspects like whether it's a read-only operation, error handling, or any rate limits, leaving significant gaps for an AI agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (two sentences) and front-loaded with key information ('Enhanced hexagram details...'), making it efficient. Every sentence adds value: the first specifies content, and the second addresses compatibility. There's no unnecessary repetition or fluff, though it could be slightly more structured for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 1 simple parameter, an output schema (which handles return values), and no annotations, the description is minimally adequate. It states the purpose and content enhancements but lacks details on behavioral traits, usage context, and parameter meaning. For a tool with low complexity, it meets basic needs but leaves gaps that could confuse an AI agent, especially without annotations to fill in behavioral aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description doesn't mention the 'hexagram_number' parameter at all, and schema description coverage is 0%, so it adds no meaning beyond the schema. However, with only 1 parameter and an output schema present, the baseline is 3 as the schema handles the input definition adequately, and the output schema can cover return values. The description fails to compensate for the lack of schema descriptions but doesn't severely hinder understanding due to simplicity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool provides 'enhanced hexagram details' with specific content elements (traditional Chinese names, Unicode symbols, rich commentary), which gives a general purpose. However, it doesn't specify the exact verb (retrieve? fetch? display?) or clearly distinguish from sibling tools like 'i_ching_divination' which might also provide hexagram information. The mention of 'backward compatibility' suggests this might replace or enhance an existing tool, but this isn't explicitly stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'i_ching_divination' or 'bibliomantic_consultation' is provided. The description implies it's for getting detailed hexagram information, but doesn't specify use cases, prerequisites, or exclusions. The backward compatibility note hints at context for existing users but doesn't help an AI agent decide when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enhanced I Ching divination with traditional three-coin method and changing lines. MAINTAINS EXACT BACKWARD COMPATIBILITY while providing richer content.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'enhanced' divination and 'richer content,' but doesn't disclose key behavioral traits such as whether it's read-only, if it has side effects, rate limits, or authentication needs. The backward compatibility note is useful but insufficient for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded, with two sentences that convey the main points efficiently. There's no unnecessary verbosity, and each sentence adds value (method details and compatibility). However, it could be more structured with clearer separation of features.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (divination with a method) and the presence of an output schema, the description covers the basic purpose and method. However, with no annotations and low parameter coverage, it lacks details on behavior and inputs. It's minimally adequate but has clear gaps in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter ('query') with 0% description coverage, and the tool description adds no information about parameters. It doesn't explain what the 'query' parameter is for, its format, or examples. With low schema coverage, the description fails to compensate, leaving parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool performs 'I Ching divination with traditional three-coin method and changing lines,' which provides a general purpose. However, it's somewhat vague about what 'enhanced' and 'richer content' mean, and it doesn't clearly differentiate from sibling tools like 'bibliomantic_consultation' or 'get_hexagram_details.' The mention of backward compatibility adds context but doesn't sharpen the core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like 'bibliomantic_consultation' or 'get_hexagram_details.' The description implies it's for I Ching divination but doesn't specify scenarios, prerequisites, or exclusions. Without explicit when/when-not instructions, it offers minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enhanced server statistics
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but fails completely. 'Enhanced server statistics' gives no indication of whether this is a read operation, a calculation, a report generation, or something else. It doesn't mention permissions required, rate limits, side effects, or what 'enhanced' means in practical terms. The description provides zero behavioral context beyond the vague name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
While technically concise (only two words), this is a case of under-specification rather than effective conciseness. The description doesn't provide enough information to be useful. Every word should earn its place, but here the words don't convey meaningful information - 'Enhanced' is vague and 'server statistics' merely repeats the tool name. This isn't front-loaded with critical information; it's just insufficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this tool has no parameters, has an output schema (which helps), and has 100% schema coverage, the description should be more complete. However, 'Enhanced server statistics' fails to explain what the tool actually does, when to use it, or what makes it 'enhanced'. For a tool with zero parameters, the description could easily provide more context about what statistics are returned, their format, or their purpose. The existence of an output schema helps, but the description itself is inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters (schema description coverage is 100%), so there are no parameters to document. The description doesn't need to compensate for any parameter documentation gaps. While it could theoretically mention that no parameters are required, this is adequately covered by the structured schema information. The baseline for zero-parameter tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Enhanced server statistics' is tautological - it essentially restates the tool name 'server_statistics' with the adjective 'Enhanced'. It doesn't specify what action the tool performs (e.g., 'retrieve', 'generate', 'analyze') or what specific statistics it provides. While it distinguishes from the three sibling tools (which are all related to divination/consultation), it doesn't clearly articulate what makes these statistics 'enhanced' compared to basic statistics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides absolutely no guidance on when to use this tool versus alternatives. It doesn't mention any context, prerequisites, or scenarios where this tool would be appropriate. Given that the sibling tools are all divination-related (bibliomantic_consultation, get_hexagram_details, i_ching_divination), there's no indication of whether this tool is part of that same domain or serves a different purpose entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
bibliomantic_consultationget_hexagram_detailsi_ching_divinationserver_statisticsScored across 4 tools
Each tool has a clearly distinct purpose: bibliomantic_consultation for general consultation, get_hexagram_details for retrieving specific hexagram information, i_ching_divination for performing divination, and server_statistics for monitoring usage. There is no overlap or ambiguity between these functions.
The naming is mixed: bibliomantic_consultation and get_hexagram_details follow a verb_noun pattern, while i_ching_divination is a noun-based name and server_statistics is a simple noun phrase. This inconsistency makes the set less predictable, though the names remain readable.
With 4 tools, the count is well-scoped for a server focused on I Ching and bibliomancy. Each tool serves a distinct role in consultation, divination, information retrieval, and monitoring, making the set efficient and purposeful.
The toolset covers core I Ching functionalities: consultation, divination, and hexagram details, with server_statistics for operational insights. A minor gap might be the lack of tools for saving or managing past consultations, but agents can work around this with existing tools.
I Ching hexagram casts, 64 hexagram meanings and changing lines for AI agents.
Divination for AI agents: Hafez, Tarot, I Ching, Runes, Geomancy, and the five-oracle Council.
Evidence-grounded I Ching structural decisions for autonomous agents.
I-Ching (周易) oracle: cast a hexagram, read classical commentary, get a reflection. Bilingual.