FateTell

Chinese astrology computed by FateTell's own BaZi engine: cast a BaZi (八字, Four Pillars) chart from any birth date, open the charts saved in your FateTell account, and check today's fortune and the Chinese almanac. Chart casting and the almanac need no account; saved charts and membership features sign in with OAuth.

GitHub

Hosted MCP Server

npx add-mcp 'https://mcp.fatetell.com/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

FateTell MCP

FateTell computes; your AI interprets.

FateTell MCP is a hosted remote MCP server (Streamable HTTP) that returns deterministic BaZi (Four Pillars) charts, Chinese almanac data and the charts saved in a FateTell account to any MCP client. The server calls no language model: the AI you already use reads and explains the results. There is nothing to download or run.

This repository holds the public metadata for that server: a plugin for Claude and Claude Code, a plugin for Cursor, an Agent Plugins package for Hermes Agent, a Gemini CLI extension, the MCP Registry entry, and the fatetell-bazi skill on how to read FateTell results. The server itself is not in this repository.

Endpoints

Endpoint	Behavior	Use it for
`https://mcp.fatetell.com/mcp`	Default. Connecting needs no account; chart casting and the almanac work anonymously. A tool that needs an account answers with an HTTP 401 challenge, and the client then opens FateTell's sign-in page.	Claude (web, desktop, mobile), Claude Code, Codex, VS Code, and most other clients
`https://mcp.fatetell.com/login/mcp`	Sign in on connect. The first request already answers 401, so sign-in happens while the client is connecting. Every tool on this endpoint is used signed in; there is no anonymous use.	Clients that start sign-in only while connecting: Cursor, Grok Bot, Manus, Gemini CLI, and Hermes Agent's own server entry
`https://mcp.fatetell.com/chatgpt/mcp`	ChatGPT's own endpoint; the tools are identical, sign-in follows ChatGPT's app conventions.	ChatGPT only

The tools, their inputs and their results are the same on every endpoint. Sign-in uses OAuth 2.1; there is no key or token to configure in advance.

Install

Claude (web, desktop, mobile)

Settings → Connectors → Add → Add custom connector. Name FateTell, URL:

https://mcp.fatetell.com/mcp

Under Authentication choose Sign in when needed (Claude detects "No sign-in" by default because the free tools work without an account; with that choice it never offers sign-in for account features). Leave the OAuth client on Claude's published identity and enter no key. Connectors follow your Claude account, so the desktop and mobile apps pick it up. Once the FateTell plugin is listed in the Claude directory, installing it from there adds the same connector together with the skill.

Claude Code

This repository is also a Claude Code plugin marketplace. The plugin adds the connector (/mcp) and the fatetell-bazi skill:

claude plugin marketplace add RussGuo/fatetell-mcp
claude plugin install fatetell@fatetell

Connector only, without the skill:

claude mcp add --transport http fatetell https://mcp.fatetell.com/mcp

Add --scope user before the name to use it in every project. To sign in ahead of time, run claude mcp login fatetell; otherwise the first account feature prompts you. /mcp shows the connection status.

Codex

codex mcp add fatetell --url https://mcp.fatetell.com/mcp

Codex opens FateTell's sign-in page right away. If the browser does not open, run codex mcp login fatetell. In the ChatGPT desktop app, Codex has its own page: Settings → Plugins → MCPs → Add, with the same URL.

ChatGPT

On chatgpt.com (or the desktop app): Plugins → Add → Add custom MCP server. Name FateTell, keep Connection on Server URL and use ChatGPT's endpoint:

https://mcp.fatetell.com/chatgpt/mcp

Keep Authentication on OAuth, leave the advanced OAuth settings alone, tick the confirmation and choose Create as a plugin. ChatGPT opens FateTell's sign-in page; choose Allow. Use this endpoint only in ChatGPT.

Cursor

Install FateTell from the Cursor Marketplace once it is listed; the plugin connects to the sign-in endpoint. To add it by hand, open this link and choose Install:

or add this entry to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "fatetell": { "url": "https://mcp.fatetell.com/login/mcp" }
  }
}

Cursor asks you to sign in to FateTell while it connects. Cursor handles a sign-in challenge only at that stage, which is why it uses /login/mcp rather than the default endpoint.

VS Code

Or from a terminal:

code --add-mcp '{"name":"fatetell","url":"https://mcp.fatetell.com/mcp"}'

The first time a chat uses a feature that needs your account, follow the prompt to sign in.

Grok Bot

Grok Bot is Cursor's cloud agent. Add FateTell as a remote MCP connector with the sign-in endpoint, or ask Grok Bot to add it for you:

https://mcp.fatetell.com/login/mcp

Manus

On manus.im: Plugins → Create → Custom MCP. Server Name FateTell, Transport Type HTTP, Server URL:

https://mcp.fatetell.com/login/mcp

Leave the headers empty and choose Save; Manus starts sign-in while connecting.

Hermes Agent

This repository is also an Agent Plugins package, which Hermes Agent installs as a plugin. The package adds the connector (/mcp) and the fatetell-bazi skill; Hermes installs it disabled, so enable it afterwards:

hermes plugins install RussGuo/fatetell-mcp --no-enable
hermes plugins enable fatetell

Once FateTell is listed in the Hermes plugin catalog, hermes plugins install fatetell installs the same package. Chart casting and the almanac work right away. The package marks the server untrusted, so Hermes asks before any tool call that is not marked read-only; create_saved_chart is the only such tool.

A plugin package cannot declare sign-in, so account features need a server entry of your own. Add this under mcp_servers in your Hermes config.yaml, next to any servers already there:

mcp_servers:
  fatetell:
    url: https://mcp.fatetell.com/login/mcp
    auth: oauth
    trust: untrusted

Then sign in:

hermes mcp login fatetell

This entry replaces the package's connector of the same name, including its trust setting, which is why it repeats trust: untrusted. It uses the sign-in endpoint because Hermes signs in only when the server asks while connecting; on the default endpoint hermes mcp login finds nothing to sign in to. Hermes stores and refreshes the tokens itself.

Gemini CLI

This repository is also a Gemini CLI extension. The extension adds the connector, on the sign-in endpoint, and the fatetell-bazi skill. Run this in a terminal, not inside a Gemini CLI session:

gemini extensions install https://github.com/RussGuo/fatetell-mcp

The first time Gemini CLI connects, it opens FateTell's sign-in page; sign in and choose Allow. Gemini CLI starts sign-in only while connecting, which is why the extension uses /login/mcp rather than the default endpoint. If no browser window opens, run this inside Gemini CLI:

/mcp auth fatetell

Gemini CLI copies the extension when it installs it; gemini extensions update fatetell picks up later changes to this repository.

Other MCP clients

Add a remote MCP server named fatetell over Streamable HTTP (often called http) with the default endpoint, OAuth for authentication and no key or header:

https://mcp.fatetell.com/mcp

If the client connects but never opens a sign-in page when an account feature is used, it is one of the clients that only signs in while connecting: use https://mcp.fatetell.com/login/mcp instead.

An agent that can run commands or edit its own MCP settings can also set itself up from install.md:

Read https://mcp.fatetell.com/install.md and follow it to connect me to FateTell MCP.

Tools

Nine tools, all deterministic. Access tiers are explained under Sign-in and permissions.

Tool	Title	Access	Scope	What it does
`cast_bazi_chart`	Cast BaZi chart	Anonymous	—	Compute a BaZi chart from birth data: pillars with Ten Gods, hidden stems, Na Yin, Day Master, all luck pillars, palaces and today's pillars; southern-hemisphere births use cross-region rules.
`get_almanac`	Get almanac	Anonymous	—	Return the Chinese almanac for one to 31 consecutive days: Gregorian and lunar dates, solar terms, and the year, month and day pillars.
`get_fatetell_account`	Get FateTell account	Signed in	`account:read`	Return the connected FateTell account: masked email, sign-in method, interface language, time zone, membership status, the permissions granted to this client, and this account's remaining quota for each tool.
`list_saved_charts`	List saved charts	Signed in	`chart:read`	List the charts saved in the connected FateTell account: id, display name, gender, whether it is the user's own chart, hemisphere, chart rule version and whether the chart has been computed.
`get_saved_chart`	Get saved chart	Signed in	`chart:read`	Return one saved chart in full: birth date, time and time zone (no birthplace), pillars with Ten Gods, hidden stems and Na Yin, all luck pillars (current one marked), palaces, the stored Day Master strength and favorable elements, and today's pillars.
`get_bazi_judgment`	Get BaZi judgment	Member	`chart:read`	Return FateTell's Day Master verdict (strong, weak, follow-strong, follow-weak) and ranked favorable, unfavorable and neutral elements under rule set v1.0, for birth data or a saved chart_id.
`get_daily_fortune`	Get daily fortune	Member	`fortune:read`	Return a saved chart's daily fortune for one date: energy level (high / medium / low), the day's stems-and-branches relations with the natal chart, the day's do/avoid items, the day pillar, this chart's year and month pillars and month clash.
`get_chart_calendar`	Get chart calendar	Member	`fortune:read`	Return a saved chart's view of upcoming dates: for each day (up to 31) the year, month and day pillars adjusted for this chart's hemisphere, relations with the natal pillars, month clash and solar terms; or for each month (up to 12) the month pillar and its natal relations.
`create_saved_chart`	Create saved chart	Member	`chart:write`	Save a new chart to the connected FateTell account from name, gender, Gregorian birth date, optional birth time and birthplace; time zone and hemisphere come from the birthplace as in the app.

create_saved_chart is the only tool that writes; it adds a chart and cannot edit or delete existing ones. Every other tool is read-only. Every result carries its rule version, and the same input always gives the same result.

Sign-in and permissions

Three access tiers; each includes everything in the tiers before it.

Tier	What you need	Tools
Anonymous	Nothing (default endpoint only)	`cast_bazi_chart`, `get_almanac`
Signed in	A FateTell account	`get_fatetell_account`, `list_saved_charts`, `get_saved_chart`
Member	An active FateTell membership	`get_bazi_judgment`, `get_daily_fortune`, `get_chart_calendar`, `create_saved_chart`

OAuth 2.1, authorization code with PKCE (S256). The authorization server is https://auth.fatetell.com; you sign in and approve on FateTell's own pages at https://web.fatetell.com. Your AI never sees your password.
Client registration: Client ID Metadata Documents and Dynamic Client Registration are both supported, so no client ID needs to be configured.
Scopes: account:read (account and membership status), chart:read (saved charts and FateTell's judgment), fortune:read (daily fortune and chart calendar), chart:write (create new charts; listed separately on the consent page), offline_access (stay connected without signing in again). ChatGPT additionally requests openid and email.
Membership is checked on every call, not fixed at sign-in. The same membership works in the FateTell app, on the website and here; what you can do here matches what you can do in the app.
Disconnecting: FateTell website → System Settings → Connected apps → Disconnect. The AI loses access within a minute.

Testing the connector

For anyone reviewing or trying the connector, with or without a FateTell account:

Connect the default endpoint, https://mcp.fatetell.com/mcp, or let a Cursor, Grok Bot or Hermes setup use the sign-in endpoint. Any email address can sign in: a code is sent to it, and the new account is free.
Without signing in (default endpoint): "Cast my BaZi chart, female, born 1 July 1990 at 10:00 in Sydney" and "What is today's day pillar?" should answer at once.
Signed in on a free account: "Read my saved chart" lists and opens the charts in that account, which is empty for a new one, so create one in the FateTell app or website first, or skip to the next step.
Member tools (Day Master judgment, daily fortune, chart calendar, saving a new chart) need an active membership. A review account with a membership and saved charts is available to directory and marketplace reviewers on request at contact@fatetell.com; it is never published in this repository.
Saving a chart is the only write: ask to "save a new chart" and the tool adds one; nothing is edited or deleted. Disconnect from the FateTell website (System Settings → Connected apps) to test revocation.

Usage limits

Every tool has a usage cap. The caps exist only to prevent abuse; they are not an allowance, they are not linked to any usage count in the FateTell app, and reaching one returns only the cap and its reset time.

Signed in: each tool has a daily cap per account, plus a combined daily cap. Days run on UTC.
Anonymous on the default endpoint: clients that do not identify anonymous users share one public cap that resets hourly. When it runs out, signing in moves you onto your own account's count.
Asking the same thing again within 24 hours does not count. One almanac lookup of 1 to 31 days counts once. Checking your account does not count.
Saved charts are also limited by the same total as in the app.

Once signed in, get_fatetell_account reports each tool's cap, current use and reset time.

Data and privacy

No language model on the server. FateTell MCP computes and reads data. It never sees your conversation with your AI.
Anonymous use is not stored. Inputs and results of cast_bazi_chart and get_almanac are not written to any database and are not linked to anyone. To avoid counting repeated questions, a result is held in server memory for up to 24 hours, keyed by a hash of the request, then discarded.
Logs record which tool ran, how long it took, the outcome, any error code and a keyed hash of the input. They never record birth dates, birth times, longitudes, place names or chart names.
Signed-in reads return only what you approved on the consent page. Saved charts are returned without the birthplace as written and without coordinates.
Saving a chart is the only feature that takes a place name: FateTell uses it to find the time zone and hemisphere, exactly as when you create a chart in the app. FateTell MCP itself does not keep or log it. Saving a chart for someone else requires their knowledge and consent.
What this repository's plugins send: the plugins contain no code. They connect only to mcp.fatetell.com; sign-in goes through auth.fatetell.com and web.fatetell.com. Nothing is sent anywhere else.

Once your AI has a result, how it stores it (for example in your chat history) is governed by that app's own policy.

BaZi results are for reference and are not a substitute for medical, legal or financial advice. How your AI interprets FateTell's data is the AI's own reading.

Privacy Policy: https://fatetell.com/privacyPolicy (section 8 covers connecting through MCP: https://fatetell.com/privacyPolicy#mcp)
Terms of Service: https://fatetell.com/terms (section 9 is the MCP service terms: https://fatetell.com/terms#mcp)
Documentation: https://fatetell.com/mcp/docs · Questions: https://fatetell.com/mcp/faq

Support and security

Support: contact@fatetell.com
Security reports: contact@fatetell.com with "Security" in the subject. Please report vulnerabilities privately rather than in a public issue.

Registry

MCP Registry name: com.fatetell/mcp. The entry is server.json and lists only the default endpoint, https://mcp.fatetell.com/mcp.

Repository contents

.claude-plugin/plugin.json        Claude plugin manifest (Claude, Cowork, Claude Code)
.claude-plugin/marketplace.json   single-plugin marketplace: this repository
.mcp.json                         Claude plugin connector: https://mcp.fatetell.com/mcp
.cursor-plugin/plugin.json        Cursor plugin manifest, connector inline: https://mcp.fatetell.com/login/mcp
plugin.json                       Agent Plugins package manifest (Hermes Agent)
mcp.json                          Agent Plugins connector: https://mcp.fatetell.com/mcp
gemini-extension.json             Gemini CLI extension manifest, connector inline: https://mcp.fatetell.com/login/mcp
skills/fatetell-bazi/SKILL.md     reading skill, shared by all four packages
server.json                       MCP Registry entry
glama.json                        Glama listing ownership: maintainers
assets/                           icons: SVG master and 1024 / 512 PNG on a paper-colored plate, a 512 white-plate variant for directory tiles, and a transparent 512 mark

Validate the Claude plugin with claude plugin validate --strict . and the Hermes package with hermes plugins validate . --install-deps.

License

The files in this repository are released under the MIT License. The license covers this repository only; the FateTell service and its calculation engine are not open source.