🧬 TAIWAN.MD · CONNECTOR

Put Taiwan in your AI

900+ sourced articles about Taiwan, one tool call away. When you ask an AI about Taiwan, it answers in Taiwan’s own voice — with citations.

Free No API key Local-first Open source

claude mcp add taiwanmd -- npx -y taiwanmd mcp serve

Paste it into your terminal → then just ask Claude about Taiwan

What it is

Taiwan.md is an open-source, AI-native knowledge base about Taiwan. This connector turns it into MCP tools, so Claude Code, Claude Desktop, Cursor, Copilot CLI and Codex CLI can search, read and cite sourced articles about Taiwan directly — instead of guessing from memory.

It deliberately goes the opposite way from a commercial data gateway:

	Taiwan.md Connector	Typical commercial MCP gateway
Price	Free	Paid / metered
API key	Not needed	Required
Where queries run	Your machine (local stdio)	Their servers
Source	Open (MIT code / CC BY-SA content)	Closed

Install

Pick your client, copy and paste. No sign-up step.

Claude Code One line

claude mcp add taiwanmd -- npx -y taiwanmd mcp serve

Zero install (via npx). Once added, just ask Claude about Taiwan.

Claude Desktop One-click bundle

Download taiwanmd.mcpb → double-click → done

⬇ Download taiwanmd.mcpb

No API-key prompt — because there is no API key.

Cursor Settings → MCP

command: npx
args: ["-y", "taiwanmd", "mcp", "serve"]

Add a new MCP server in Cursor’s settings.

Copilot CLI / Codex CLI / Cline / Continue / any MCP client Universal stdio

npx -y taiwanmd mcp serve

Any client that speaks MCP works — point it at this stdio command.

Remote · any MCP client mcp-remote

npx mcp-remote https://mcp.taiwan.md

For thin clients that can’t run Node / pure web. Local-first is still recommended (best privacy).

You can print the right snippet anytime: npx -y taiwanmd mcp install --client claude-code

MCP tools 6

Once installed, Claude picks the tools itself. taiwanmd_cite is the anti-hallucination weapon: it returns only sentences backed by a footnote + source URL, so every fact you write about Taiwan is traceable.

taiwanmd_search

Full-text search across 900+ Taiwan articles (zh + en)

in { "query": "半導體", "limit": 5 }

out Top-N hits: title / slug / category / description

taiwanmd_read

Read a full article by slug (frontmatter + body)

in { "slug": "珍珠奶茶" }

out Full markdown body

taiwanmd_rag

Top-N articles assembled into a prompt-ready RAG context block

in { "query": "台灣健保", "limit": 3 }

out LLM-ready context + the question

taiwanmd_cite anti-hallucination

Anti-hallucination primitive: only sentences with a footnote + source URL

in { "query": "台積電", "limit": 3 }

out claim + article + sources[{ name, url }]

taiwanmd_organs

Live health scores for the Semiont’s 8 organs

in {}

out Organism vitals (heart / immune / DNA …)

taiwanmd_stats

Project stats: article count / categories / timestamps

in {}

out totalArticles / byCategory

CLI tools 26

Same knowledge base, straight from your terminal. Install globally or run zero-install:

npm install -g taiwanmd   # or zero-install: npx taiwanmd search 珍珠奶茶

🔍Read & explore

`search <query>`	Fuzzy search (zh + en, --json to pipe)	`taiwanmd search 珍珠奶茶`
`read <slug>`	Read a full article in the terminal (--raw / --en / --web)	`taiwanmd read 珍珠奶茶 --raw`
`list [category]`	Browse by category (--categories for all)	`taiwanmd list food`
`random`	Discover a random article	`taiwanmd random --category nature`
`today`	Today in Taiwan: 3 picks + a fun fact	`taiwanmd today`
`quiz`	Taiwan knowledge quiz (5 true/false)	`taiwanmd quiz`
`explore`	Interactive fuzzy-search TUI	`taiwanmd explore`
`graph <slug>`	An article’s [[wikilink]] relation graph	`taiwanmd graph 珍珠奶茶`
`diff`	Knowledge-base changes over the last 7 days	`taiwanmd diff`
`terminology`	Taiwan / China terminology lookup & conversion	`taiwanmd term 滑鼠`

🤖AI · RAG

`rag <query>`	Top articles as prompt-ready context (pipe to an LLM)	`taiwanmd rag "台灣經濟"`
`cite <query>`	Anti-hallucination: verifiable claims with source URLs	`taiwanmd cite 台積電`
`mcp serve`	Start the MCP server (for Claude and other clients)	`taiwanmd mcp serve`

✍️Contribute · quality

`contribute <topic>`	Interactive, guided new-article creation	`taiwanmd contribute 阿里山`
`validate <slug>`	Single-article quality scorecard	`taiwanmd validate 珍珠奶茶`
`audit <slug>`	Stage 3.5 hallucination audit (MANIFESTO §10)	`taiwanmd audit 王新仁`
`inbox`	Read / manage the ARTICLE-INBOX	`taiwanmd inbox --state pending`
`sync`	Sync the knowledge base locally	`taiwanmd sync`

🧬Organism · Semiont

`organs`	Bar chart of the 8 organ health scores	`taiwanmd organs`
`stats`	Project stats + organism health	`taiwanmd stats`
`sense`	Sense data: GA4 / Search Console / Cloudflare	`taiwanmd sense`
`spore`	Community spores (SPORE-LOG)	`taiwanmd spore log`
`supporters`	Portaly supporter stats (de-identified by default)	`taiwanmd supporters`

🔧Utilities

`profile`	Manage your contributor profile	`taiwanmd profile`
`mailmap`	Inspect / manage .mailmap identity merges	`taiwanmd mailmap`

How it works · privacy

Local stdio — the server runs as a process on your machine, not a remote service. Your questions never go to any Taiwan.md server.
One-time auto-sync — the knowledge base downloads once to ~/.taiwanmd, then it’s fast and quiet locally. Inside the repo it reads knowledge/ directly.
Open & verifiable — the MCP server is 145 lines (cli/src/lib/mcp-server.js); read every line before you install.
License — content CC BY-SA 4.0, code MIT. Fork freely.

FAQ

Does it cost anything? Do I need an API key?

Neither. Taiwan.md is a public good (CC BY-SA); knowledge queries have no gate. No account, no key, no billing.

Where do my queries go?

Nowhere. The MCP server is a local stdio process on your own machine; queries are not sent out. First use downloads the knowledge base to ~/.taiwanmd, then everything stays local.

First query feels slow?

That’s the one-time knowledge-base sync running. The server pre-warms on start, so it’s fast afterwards.

npx not found?

Node.js 18+ ships npx. To pin a version, use npx -y [email protected] mcp serve.

Is there a remote endpoint?

Yes: https://mcp.taiwan.md (free, read-only, no key). Connect any MCP client with npx mcp-remote https://mcp.taiwan.md. For thin clients that can’t run Node — but local-first is always the recommended path (best for privacy); remote is just an optional entry point.

Open source · the Semiont’s body

This connector is part of Taiwan.md’s reproduction system — letting Taiwan’s voice live inside every developer’s AI session. Forks, contributions and reports are welcome.

GitHub npm Docs Contribute

🧬