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.

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: timedoctor-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:

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:

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

Dependency advisories

Dev/build tooling (vitest, vite, esbuild) and a transitive (jsondiffpatch) are pinned to patched versions. The remaining Dependabot alerts live in the agents SDK chain (@ai-sdk/provider-utils, ai, and agents' own AI-Playground / OAuth-callback / email-routing advisories). None are reachable here — this server exposes no playground, OAuth flow, or email routing — and the only offered upgrade (agents@0.16) forces a zod 3→4 major that conflicts with the MCP SDK. They are tracked, not exploitable, and will be cleared when agents ships a zod-3-compatible patch.

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.