FateTell MCP
by RussGuo
README.md
# FateTell MCP
[](https://glama.ai/mcp/connectors/com.fatetell/mcp)
[](https://registry.modelcontextprotocol.io/v0/servers?search=com.fatetell/mcp&version=latest)
English · [简体中文](README.zh-CN.md)
FateTell computes; your AI interprets.
FateTell MCP is a hosted remote MCP server (Streamable HTTP) for BaZi (八字, Four Pillars of Destiny). It returns deterministic BaZi charts, Chinese almanac data and the charts saved in a FateTell account to Claude, ChatGPT, Cursor and any other 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.
```
https://mcp.fatetell.com/mcp
```
## At a glance
| | |
|---|---|
| Type | Hosted remote MCP server, Streamable HTTP. Nothing to install or run locally. |
| Endpoint | `https://mcp.fatetell.com/mcp` (two more for clients with their own sign-in flow, see [Endpoints](#endpoints)) |
| Works with | Claude (web, desktop, mobile), ChatGPT, Cursor, Claude Code, Codex, VS Code, Gemini CLI, Grok Bot, Manus, Hermes Agent and other clients that speak Streamable HTTP |
| Authentication | None for chart casting and the almanac. OAuth 2.1 for account features. No API key. |
| Tools | 9, all deterministic: 2 anonymous, 3 signed in, 4 for members ([list](#tools)) |
| Input | Birth date (Gregorian, or Chinese lunar with leap months), clock time, IANA time zone, gender, hemisphere; longitude only when true solar time is requested |
| Output | Structured data: four pillars with Ten Gods, hidden stems and Na Yin, luck pillars, palaces, solar terms; every result carries its rule version |
| Conventions | A birth from 23:00 counts toward the next day's pillar; the year changes at the Start of Spring; true solar time is off by default and applied on request; southern-hemisphere births adjust the month pillar. Each result states whether true solar time and the hemisphere adjustment were applied. |
| Chart card | Rendered in the conversation by hosts that support MCP Apps; the skill carries a static HTML template for the others |
| Language model | None on the server |
| Cost | FateTell does not charge for MCP use. Member tools need a FateTell membership, the same one as in the app. |
| Limits | Per-tool caps that only prevent abuse ([Usage limits](#usage-limits)) |
| Docs | [fatetell.com/mcp/docs](https://fatetell.com/mcp/docs) in eight languages · [FAQ](https://fatetell.com/mcp/faq) |
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:
```sh
claude plugin marketplace add RussGuo/fatetell-bazi-mcp
claude plugin install fatetell@fatetell
```
Connector only, without the skill:
```sh
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
```sh
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**:
[](cursor://anysphere.cursor-deeplink/mcp/install?name=fatetell&config=eyJ1cmwiOiJodHRwczovL21jcC5mYXRldGVsbC5jb20vbG9naW4vbWNwIn0=)
or add this entry to `~/.cursor/mcp.json`:
```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
[](https://vscode.dev/redirect/mcp/install?name=fatetell&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.fatetell.com%2Fmcp%22%7D)
Or from a terminal:
```sh
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:
```sh
hermes plugins install RussGuo/fatetell-bazi-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:
```yaml
mcp_servers:
fatetell:
url: https://mcp.fatetell.com/login/mcp
auth: oauth
trust: untrusted
```
Then sign in:
```sh
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:
```sh
gemini extensions install https://github.com/RussGuo/fatetell-bazi-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.
A client that can only start local (stdio) servers can reach the same endpoint through [`mcp-remote`](https://github.com/geelen/mcp-remote), a third-party open-source bridge:
```sh
npx -y mcp-remote https://mcp.fatetell.com/mcp
```
```json
{
"mcpServers": {
"fatetell": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.fatetell.com/mcp"] }
}
}
```
The bridge only relays requests; every calculation still runs on FateTell's servers. It has been checked with the tools that need no account. For account features, prefer a client that connects to remote servers itself.
An agent that can run commands or edit its own MCP settings can also set itself up from [install.md](https://mcp.fatetell.com/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](#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:
1. 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.
2. 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.
3. 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.
4. 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.
5. 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
## Questions
**Is there a hosted BaZi MCP server that needs no local install?**
Yes, this one. Add `https://mcp.fatetell.com/mcp` as a remote MCP server in Claude, ChatGPT (with its own endpoint), Cursor or another client. Nothing runs on your machine.
**How is it different from a local BaZi MCP server started with `npx`?**
A local server is a package you install and run next to your AI client, so it needs Node or Python and a desktop client. FateTell MCP runs on FateTell's servers and is reached by URL, so it also works in web and mobile clients that cannot start a local process. After sign-in it can read the charts saved in a FateTell account, which a local package cannot. The calculation engine is not open source; the rules it follows are stated in every result.
**Do I need a FateTell account or an API key?**
No account for chart casting and the almanac, and never an API key. Saved charts need a FateTell sign-in; the Day Master judgment, daily fortune, chart calendar and saving a chart need a FateTell membership.
**Does the server interpret the chart?**
No. It returns computed data only. Your AI writes the reading, and the `fatetell-bazi` skill in this repository tells it how to read the data.
**Why does a chart here differ from another tool's?**
Usually true solar time (off by default here, as in the FateTell app), the southern-hemisphere month pillar, or a missing birth time (cast at 12:00, with the hour pillar for reference only). The [FAQ](https://fatetell.com/mcp/faq) has the details.
## 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`](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
README.zh-CN.md this README in Simplified Chinese
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](LICENSE). The license covers this repository only; the FateTell service and its calculation engine are not open source.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues