Skip to main content
Glama
Torn MCP Server
by Yoonutz

Torn MCP Server

License: MIT Cloudflare Workers MCP

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 (X-Api-Key and Authorization: Bearer <key> are accepted too, for clients that restrict header names); it is never stored, never shown to the model, and never read from the URL (see Security & privacy). Clients that can't set headers (Claude's connector directory) sign in with OAuth instead: you paste the key once on the server's sign-in page.

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 192 endpoints across 239 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.

NOTE

Read-only. The Torn API v2 exposes onlyGET endpoints - this server can never modify your account or take in-game actions.

Install

Live endpoint (hosted instance):

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

One-click install:

Install in VS Code Install in VS Code Insiders Install in Cursor

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

Claude Code Claude Desktop Windsurf Visual Studio Continue

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" }
    }
  }
}

Customize → Connectors → Add custom connector:

  • MCP server URL: https://torn-mcp.yoonutz.workers.dev/mcp

  • Authentication: No sign-in

  • Request headers: pick x-api-key from the list and paste your Torn API key as the value. Do not choose Custom header with X-Torn-Api-Key: Anthropic only sends pre-approved header names, so the save is rejected. The server accepts x-api-key as an alias.

The Request headers section is an Anthropic beta. If the dialog does not show it, your account does not have it yet; use the config-file route below or Claude Code instead.

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

Tool

Endpoints

Example endpoint values

torn_user

71

ammo, attacks, attacksfull, bars, basic, battlestats

torn_faction

43

applications, attacks, attacksfull, balance, basic, chain

torn_torn

40

attacklog, bank, bounties, calendar, cards, cityshops

torn_company

10

applications, employees, news, companies, profile, search

torn_market

9

auctionhouselisting, auctionhouse, bazaar, itemmarket, properties, pointsmarket

torn_racing

8

cars, carupgrades, races, race, records, tracks

torn_forum

6

categories, posts, thread, threads, lookup, timestamp

torn_property

3

property, lookup, timestamp

torn_key

2

log, info

torn_list_endpoints

-

discovery: lists every endpoint per tag

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:

Tool

Aggregates

Returns

analyze_player

user/profile + personalstats

status, activity, life, social, stats

summarize_player

user/profile

condensed one-glance snapshot

compare_players

user/profile ×N

side-by-side + level gap to top

summarize_faction

faction/basic + members

counts by position and activity

faction_member_activity

faction/members

online / idle / offline buckets

war_readiness_report

faction/members

availability-based readiness score

territory_summary

faction + torn territory

holdings + global sample

crime_analysis

faction/crimes

status/difficulty counts, success rate

summarize_company

company/profile + employees

profile + headcount

item_market_analysis

market/itemmarket + torn/items

depth, price band, market value

market_analysis

market/itemmarket ×N

items ranked by spread

find_profitable_items

market/itemmarket + torn/items ×N

items ranked by margin

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 a request header only (X-Torn-Api-Key, or the X-Api-Key / Authorization: Bearer aliases) - 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.

  • Header keys are never stored and never returned in error messages.

  • OAuth sign-in (for clients without custom headers): the key you paste on /authorize is stored only AES-GCM-encrypted under a key derived from your access/refresh token, which only your client holds; the server keeps no secret that can decrypt it. Tokens are single-purpose (tmcp_…), access tokens last 24 h, refresh tokens 180 days and rotate on use; expired records delete themselves. A request with no key and no token gets 401 pointing at the OAuth metadata.

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

Full policy for the hosted instance: PRIVACY.md. Support: GitHub issues.

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      MCP server for Interactive Brokers API, enabling account management, trading, market data, options, scanners, and news via natural language.
      33
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Request Tracker REST2 API, enabling ticket, queue, user, and asset management via natural language.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Remote MCP server providing live Warframe data via Warframe.market and WarframeStat.us APIs. Enables price checks, worldstate lookups, item/drop searches, and more through natural language tools.
      61 npm
      MIT