Helldivers2 MCP Server

helldivers2-mcp

A stateless Model Context Protocol (MCP) server that exposes live Helldivers 2 galactic war data to LLMs.

Data is sourced from the community API at api.helldivers2.dev.

---

Tools

---

Quickstart

Prerequisites

• Node.js 22+ or Docker
• A contact email for the X-Super-Contact header (required by the upstream API)

Local dev

cp .env.example .env   # set X_SUPER_CONTACT=your@email.com
npm install
npm dev               # hot-reload via tsx watch on :3000

Production build

npm build   # tsc → dist/
npm start

Docker

docker build -t helldivers2-mcp .
docker run -p 3000:3000 -e X_SUPER_CONTACT=your@email.com helldivers2-mcp

---

Configuration

All configuration is via environment variables.

---

Endpoints

The server uses the stateless Streamable HTTP transport. Each POST /mcp request creates a fresh McpServer + transport pair, handles the request, then tears them down. There is no session state.

---

Connecting to Claude Desktop

Hosted server (easiest)

A public instance is available at https://mcp.avengersofsuperearth.com/mcp. No setup required — just add it to your claude_desktop_config.json:

{
  "mcpServers": {
    "helldivers2": {
      "url": "https://mcp.avengersofsuperearth.com/mcp"
    }
  }
}

Self-hosted (local binary)

{
  "mcpServers": {
    "helldivers2": {
      "command": "node",
      "args": ["/path/to/helldivers2-mcp/dist/index.js"],
      "env": {
        "X_SUPER_CONTACT": "your@email.com"
      }
    }
  }
}

Self-hosted (HTTP server)

{
  "mcpServers": {
    "helldivers2": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

---

Development

npm test              # Jest (ESM mode)
npm test:watch
npm test:coverage
npm lint              # ESLint

Run a single test file:

npm test src/__tests__/tools.war.test.ts

Adding a tool

1. Create src/tools/your-tool.ts and export a Tool object with .definition and .handler.
2. Import it and add it to the TOOLS array in src/index.ts.
3. Return textResponse(...) on success or errorResponse(...) on failure — never throw from a handler.
4. All upstream calls must go through hd2Fetch (in-memory 2-minute cache + rate-limit-aware queue).

---

License

MIT