Torn MCP Server

A remote Model Context Protocol server for the Torn City API v2, running on Cloudflare Workers. Connect from VS Code (or any MCP client) anywhere — no local install. You supply your Torn API key via the X-Torn-Api-Key header; it is never stored, logged, or shown to the model.

Tools: one grouped tool per Torn tag (torn_user, torn_faction, torn_torn, torn_company, torn_market, torn_racing, torn_forum, torn_property, torn_key) covering all 205 API paths via an endpoint argument — plus 12 intelligence tools that aggregate endpoints into structured summaries (analyze_player, war_readiness_report, find_profitable_items, …) and torn_list_endpoints for discovery.

Use it (client setup)

The deployed endpoint is:

https://torn-mcp.yoonutz.workers.dev/mcp

(This is the live hosted instance. Or run your own — see Deploy. Add a custom domain later to drop the workers.dev host.)

VS Code — user-level mcp.json (works from any workspace):

{
  "servers": {
    "torn": {
      "type": "http",
      "url": "https://torn-mcp.yoonutz.workers.dev/mcp",
      "headers": { "X-Torn-Api-Key": "YOUR_TORN_API_KEY" }
    }
  }
}

Same url + headers block works for Claude Desktop, Cursor, Windsurf, and Continue under their mcpServers/servers config.

Related MCP server: Telnyx MCP Server

Get a Torn API Key

Torn → Settings → API Keys → create a key. A Limited or Minimal key covers most tools; faction/market selections may need broader scope. Paste it into the X-Torn-Api-Key header.

Tools

One grouped tool per Torn tag, each covering all of that tag's endpoints:

Each tool takes:

• endpoint (required) — which data type to fetch (full list per tool, or call torn_list_endpoints).

• id (optional) — entity id; used when the endpoint is entity-scoped or requires one.

• params (optional) — extra query options (limit, from, to, sort, cat, …).

The Torn key is not a tool parameter — it comes from the request header, so it never enters model context or client transcripts.

Intelligence tools

Higher-level tools that aggregate multiple endpoints and return structured summaries instead of raw JSON:

War readiness is availability-based (okay/hospital/traveling, online, on-wall, in-OC) — per-member battlestats are not exposed by the Torn API.

Deploy

Prereqs: Node 18+, a Cloudflare account, npx wrangler login once.

git clone https://github.com/Yoonutz/torn-mcp.git
cd torn-mcp
npm install
npx wrangler deploy

After the first deploy, wrangler prints your live URL: https://torn-mcp.yoonutz.workers.dev. The MCP endpoint is that URL + /mcp.

Optional: server-level fallback key

By default the server is multi-tenant — every request must carry X-Torn-Api-Key. To set a fallback key used when the header is absent (makes header-less callers single-tenant):

npx wrangler secret put TORN_API_KEY

The secret is never exposed to the model and never logged.

Custom domain (optional)

Default *.workers.dev URLs include your account subdomain. To use your own domain (must be on Cloudflare), uncomment the routes block in wrangler.toml, set the pattern, and redeploy. The endpoint becomes https://<your-pattern>/mcp.

Test with MCP Inspector

Before wiring a client, verify the server with the MCP Inspector:

npx @modelcontextprotocol/inspector

In the Inspector: transport Streamable HTTP, URL = your /mcp endpoint, add header X-Torn-Api-Key: YOUR_TORN_API_KEY. Connect → list tools → call torn_torn with endpoint=timestamp to confirm a live response.

Security & privacy

• Key supplied via X-Torn-Api-Key header only — never a tool parameter.

• Never stored, never logged, never returned in error messages.

• Upstream calls are pinned to https://api.torn.com (SSRF guard) with User-Agent: torn-mcp.

• Per-key rate limiting (~100 req/min, Torn's cap) via a Durable Object — returns a clear error instead of hammering Torn.

Development

npm run dev        # local dev server (wrangler dev)
npm run test       # unit tests (vitest)
npm run typecheck  # tsc --noEmit
npm run deploy     # wrangler deploy
npm run cf-typegen # regenerate Worker binding types

Run npm run sync-openapi to pull the latest Torn spec and regenerate src/generated/endpoints.ts.

Scope & roadmap

Covered: all 9 Torn tags (160 endpoints / all 205 paths) as raw JSON, plus 12 intelligence tools and a discovery tool. Still on the roadmap from the retired Fastify/Docker design (superseded spec): MCP resources, prompts, and richer per-endpoint output typing.

License

MIT — // @license MIT headers are included in all source files.