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, never shown to the model, and never read from the URL (see Security & privacy).

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 187 endpoints across 234 operations of the spec 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.

Install

Live endpoint (hosted instance):

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

One-click install:

Click a badge → the client opens with the server pre-filled. It installs with a YOUR_TORN_API_KEY placeholder — replace it with your real key (get one) in the client's MCP settings after install.

Setup guides (these clients have no one-click protocol — badge links to their MCP docs; use the config blocks below):

Or set it up manually — pick your client below. Prefer to self-host? See Deploy.

claude mcp add --transport http torn https://torn-mcp.yoonutz.workers.dev/mcp \
  --header "X-Torn-Api-Key: YOUR_TORN_API_KEY"

Check it: claude mcp list. Remove: claude mcp remove torn.

macOS / Linux (bash, zsh):

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

Windows PowerShell — escape the inner quotes with \" (the code.cmd shim strips plain quotes otherwise):

code --add-mcp '{\"name\":\"torn\",\"type\":\"http\",\"url\":\"https://torn-mcp.yoonutz.workers.dev/mcp\",\"headers\":{\"X-Torn-Api-Key\":\"YOUR_TORN_API_KEY\"}}'

Insiders: use code-insiders. Then open Copilot Chat → Agent mode → 🛠️ tools and enable torn. (If quoting still fights you, use the manual mcp.json below — no escaping needed.)

Manual alternative — user mcp.json (Command Palette → MCP: Open User Configuration):

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

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

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

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "torn": {
      "serverUrl": "https://torn-mcp.yoonutz.workers.dev/mcp",
      "headers": { "X-Torn-Api-Key": "YOUR_TORN_API_KEY" }
    }
  }
}

Settings → Developer → Edit Config (claude_desktop_config.json). Recent versions accept a remote URL directly:

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

If your version only supports stdio servers (the connection fails), use the mcp-remote bridge instead:

{
  "mcpServers": {
    "torn": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://torn-mcp.yoonutz.workers.dev/mcp",
        "--header",
        "X-Torn-Api-Key:YOUR_TORN_API_KEY"
      ]
    }
  }
}

Restart Claude Desktop.

Add a .mcp.json to your solution or %USERPROFILE%\.mcp.json:

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

Edit ~/.continue/config.yaml:

mcpServers:
  - name: torn
    type: streamable-http
    url: https://torn-mcp.yoonutz.workers.dev/mcp
    requestOptions:
      headers:
        X-Torn-Api-Key: YOUR_TORN_API_KEY

The Claude Code and VS Code CLI commands above are tested. The other clients use the same endpoint + X-Torn-Api-Key header (verified working), but their config key names and file paths can change between versions — check the client's own MCP docs if a connection fails.

Security: putting the key inline lands it in config files / shell history. Where the client supports it (e.g. VS Code ${input:...} prompts), prefer that over a plaintext key.

Related MCP server: rt-mcp

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 (table generated from the committed spec by npm run generate; counts are checked by the contract test):

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. Item endpoints (market/itemmarket, market/bazaar, torn/items) also accept an item name; ids endpoints accept a comma-separated numeric list; torn/itemdetails and torn/itemstats take item uids, never names.

• params (optional) — extra query options (limit, from, to, sort, cat, …). Only the params the called variant accepts are allowed; anything else is rejected with the accepted list, so a typo cannot be silently ignored by Torn.

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

Errors and non-JSON responses

• Torn reports every error as HTTP 200 with a JSON envelope { "error": { "code": N, "error": "..." } }; the OpenAPI spec documents only the 200 success shape. The server detects the envelope on every endpoint and returns it as a tool error Torn API error N: message.

• Three endpoints (user/snapshot, faction/snapshot, company/snapshot) answer CSV, not JSON (the spec documents text/csv). They are marked [csv] in the tool description and return { "csv": "<text>", "format": "text/csv" } in the structured channel with the raw CSV as text — no pagination, no enrichment.

• Any other non-JSON body is reported as Torn API returned a non-JSON response.

Intelligence tools

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

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

Security & privacy

• Key supplied via the X-Torn-Api-Key header only — never a tool parameter, and never read from the URL. A ?key= query parameter is ignored (the request fails with a "send the header" error), and the query string is not forwarded past the Worker's front door.

• Never stored, never returned in error messages.

• Logging, precisely: this code writes no logs. Cloudflare Workers invocation logs (which would record <Method> <URL> per request) are switched off in wrangler.toml ([observability.logs] invocation_logs = false), so a request URL is not persisted even if a misconfigured client puts a key in it. What this repository cannot control: Cloudflare's own edge/analytics data, and the upstream leg — the key reaches api.torn.com as the key query parameter Torn documents, which is Torn's log surface, not ours.

• 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.

Dependencies

The deployed Worker's runtime dependencies are @modelcontextprotocol/sdk and zod. Dev/build tooling advisories are pinned to patched versions via overrides in package.json (esbuild, js-yaml, ws); npm audit is part of the release check — see SECURITY.md.

Scope & roadmap

Covered: all 9 Torn tags — every documented data endpoint (the counts in the table above are derived from the committed spec) as raw JSON, plus 12 intelligence tools and a discovery tool. The spec is re-synced from Torn weekly; see docs/ROADMAP.md for what shipped and what is proposed (MCP resources, prompts, richer per-endpoint output typing).

License

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