MCP

For: someone connecting Ziwei to a chat client for the first time. No library to install, no code to write.

On Cursor and Claude, install the plugin. The Skill calls chart / to_text first, then explains. ChatGPT imports a plugin marketplace under B. Connectors. Other clients use the same URL and the instructions in C. When there is no Skill.

A local stdio process does not apply: this is public HTTP, and there is no command to start. Names, required fields and response shapes are written in the second half of this page.

A. Install the plugin

On Cursor and Claude, install the plugin. The plugin ships the Skill, and the Skill calls chart or to_text before any reading.

Claude Code

This is the user install today.

claude plugin install ziwei --marketplace x-haose/x-ziwei

The plugin's .mcp.json uses type: http (Claude Code also accepts the alias streamable-http). No authentication. Components stay at the plugin root. They do not go inside .claude-plugin/.

Cursor

The user path is install, reload, then ask in plain language. No terminal.

The official Marketplace listing is not submitted, so you cannot install from the store today. Do not read the steps below as something you can finish in the store right now. Once it is listed, install it from the Marketplace.

Team and Enterprise can import from the repo today. That is still not the public store: Dashboard → Plugins & MCPs → Import. An admin imports the x-ziwei repository. Members then enable the plugin in Cursor.

B. Connectors

ChatGPT installs by importing a plugin marketplace. The steps are below. Clients without a plugin shell put the same public URL into the connector. Those connections do not ship this repo's Skill. After connecting, paste the instructions in C into the system prompt or custom instructions.

Only entry points that the current docs can check are written here. A product without an official plugin shell is not a published catalog plugin.

ChatGPT

Today's install is Plugins → Add → Import marketplace. Set Source to the GitHub repository, authorize GitHub, import the marketplace, then install ziwei. A listing in the public plugin directory is a separate path, and it is not ready.

The same Add menu has three items. Each one does a different job:

• Import marketplace imports a marketplace from GitHub. This is how you install ziwei. The current Chinese client labels this item 添加插件市场.
• Create a plugin scaffolds a plugin package. The ziwei install is Import marketplace.
• Record a skill records a skill. It does not install an MCP server.

The official write-up is a workspace admin import: Admin Console → Plugins → Add → Import marketplace, with the fields Source and Path, and the confirm control is also Import marketplace. The personal client's Chinese menu says 「添加插件市场」. Whether those two forms have the same fields is not confirmed on a real device. See Importing and syncing plugin marketplaces from GitHub.

Grok

On the web, open grok.com/connectors, choose New Connector, then Custom, and set the URL to https://ziwei.x-haose.com/mcp. This service has no authentication. If the dialog asks for auth, leave it empty or skip OAuth. For Grok Business and Enterprise, a team admin must add the connector in the console before members can use it. See Connectors.

Grok Build can also write the config. The command records it in ~/.grok/config.toml:

grok mcp add --transport http ziwei https://ziwei.x-haose.com/mcp

Or by hand:

[mcp_servers.ziwei]
url = "https://ziwei.x-haose.com/mcp"

See MCP Servers. Then paste the instructions in C.

Codex

Codex stores a Streamable HTTP server in ~/.codex/config.toml. A trusted project can use .codex/config.toml in the project instead. The ChatGPT desktop app, the Codex CLI and the IDE extension share this file.

[mcp_servers.ziwei]
url = "https://ziwei.x-haose.com/mcp"

The equivalent command:

codex mcp add ziwei --url https://ziwei.x-haose.com/mcp

Do not add a bearer token, and do not run codex mcp login. When no credential source resolves, Codex connects without authentication. In the desktop app or the IDE, choose Streamable HTTP and the same URL. See Model Context Protocol.

For the OpenAI Agents SDK on hosted Responses calls, use HostedMCPTool with server_url set to https://ziwei.x-haose.com/mcp. To connect inside the process, use MCPServerStreamableHttp with params["url"] set to the same address. Neither call should send an Authorization header.

C. When there is no Skill

Any client that can take a remote MCP URL uses https://ziwei.x-haose.com/mcp, with no auth header. When there is no Skill channel, paste one of the blocks below into the system prompt or custom instructions. The rules match the plugin Skill.

English

You interpret Zi Wei Dou Shu charts. The only MCP endpoint is https://ziwei.x-haose.com/mcp. The only tools are chart and to_text.

Rules:
- Never invent a chart, star placement, mutagen, or decade from memory. No tool result means no chart.
- Always call chart and/or to_text first, then interpret in plain language.
- Do not invent a third tool. There is no lookup.
- Interpretation belongs to you. The engine only casts the chart and is gold-aligned with iztro. Do not rewrite the result into a different set of stars.
- If a tool fails, say so. Do not fill in a fake chart, and do not guess the hour.

Solar minimum for both tools: calendar=solar, date=YYYY-M-D, timeIndex=0-12, gender=male or female.
Ask when the hour is unknown. Lunar dates also require leap: notLeap, leap, or leapFixed.
Use chart for the structured chart and to_text for Markdown. For a horoscope, pass targetDate and targetTimeIndex to chart; set includeHoroscope=true on to_text with the same target date and hour.

中文

你是紫微斗数解读助手。公网 MCP 只有 https://ziwei.x-haose.com/mcp，工具只有 chart 与 to_text。

硬规则：
- 禁止凭记忆编造命盘、星曜、四化或大限。没有工具结果就没有盘。
- 先调用 chart 和/或 to_text，再用人话解释。
- 不要发明第三个工具，没有 lookup。
- 解释属于你。引擎只排盘，盘面与 iztro 金标对齐。不要改写成另一套星曜。
- 工具失败就说明错误，不要补假盘，也不要猜时辰。

阳历最短入参（chart 与 to_text 相同）：calendar=solar，date=YYYY-M-D，timeIndex=0-12，gender=male 或 female。
时辰不明先问。农历必须另给 leap：notLeap、leap 或 leapFixed。
要盘面用 chart；要 Markdown 用 to_text。运限时 chart 同时给 targetDate 与 targetTimeIndex；to_text 设 includeHoroscope=true 并带同样的目标日、时。

Compatibility / debugging

Pasting JSON only attaches the URL. It does not install the Skill. When a plugin exists, use A. These shapes are for a plugin that did not load, or for a client that only has a config file.

Cursor's user config is ~/.cursor/mcp.json. For one project only, use .cursor/mcp.json in that project. The plugin's own mcp.json is this same object:

{
  "mcpServers": {
    "ziwei": {
      "url": "https://ziwei.x-haose.com/mcp"
    }
  }
}

Claude adds "type": "http". For Claude Code, put it in .mcp.json at the project root, or under mcpServers in your user config. Claude Desktop and claude.ai custom connectors that ask for JSON use the same block:

{
  "mcpServers": {
    "ziwei": {
      "type": "http",
      "url": "https://ziwei.x-haose.com/mcp"
    }
  }
}

Cascade (Windsurf / Devin Desktop) uses serverUrl for a remote HTTP entry. Open the config from the MCP menu and write it there. The current Devin docs default to ~/.config/devin/mcp_config.json (or that directory under XDG_CONFIG_HOME when it is set):

{
  "mcpServers": {
    "ziwei": {
      "serverUrl": "https://ziwei.x-haose.com/mcp"
    }
  }
}

If other servers are already there, merge the "ziwei" entry. Do not replace the whole file. A local stdio MCP server does not apply.

What to say once it is installed

You do not need the parameter names. Say it in plain language and the model fills them in. With the plugin installed, “阳历 2000-8-16 寅时女命，排紫微盘” is enough. The reply must call the tool first.

The first line casts the natal chart for 16 August 2000, Tiger hour, female. Tiger hour is time index 2 (03:00–05:00). The model converts that itself.

The second line makes the model fetch the chart as Markdown and explain it from that text. to_text returns the facts of the chart (with the built-in knowledge pack by default), not a finished reading of "how is this person's career". The words are the model's. The numbers are the tool's.

Say them as two turns, or in one message.

The frozen contract

There are two tools. The required fields and response keys below are the part you can pin: optional fields may be added later; these names and keys will not be renamed or removed.

The shortest solar input, the one behind "solar 2000-8-16, Tiger hour, female":

{
  "calendar": "solar",
  "date": "2000-8-16",
  "timeIndex": 2,
  "gender": "female"
}

Both tools share this set of birth parameters:

The default chart language is simplified Chinese. Feeding the model a Chinese chart is more reliable than feeding it iztro's English star glosses. See Letting an AI read the chart.

chart

The chart as JSON. The response is { "astrolabe": { ... } }, aligned with x-iztro's to_dto(). Contract keys are the language-independent *_key fields.

For a horoscope, add a target date. Both fields together, or the response has no horoscope:

to_text

The same birth parameters, and the response is { "text": "..." }. text is Markdown. It is not the instruction-bearing prompt from astrolabe_to_prompt. The format is documented on Semantic text.

Hours

timeIndex is not a clock hour. Zi is split into a head and a tail, so the index runs 0–12.

What it does not do

• It does not write the reading. to_text is the chart in words. The interpretation is what the model says after reading that text.
• It does not accept a chart the model placed itself, or stems and branches the model invented.
• It does not replace embedding the library in your own product. That path is still Rust, Python or Go — see Getting started and Letting an AI read the chart.