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 [email protected]
npm install
npm run dev               # hot-reload via tsx watch on :3000

Production build

npm run build   # tsc → dist/
npm run start

Docker

Image is available on Docker Hub.

docker pull xerno42/helldivers2-mcp # pull from Docker Hub
# or
docker build -t helldivers2-mcp . # build locally

#then run with:
docker run -p 3000:3000 -e [email protected] 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.

Usage in Code

Call the MCP server directly over HTTP using the Streamable HTTP transport. Each request is a JSON-RPC tools/call message sent to POST /mcp.

JavaScript / TypeScript

Using the official MCP TypeScript SDK:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "my-app", version: "1.0.0" });

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.avengersofsuperearth.com/mcp")
);

await client.connect(transport);

// List available tools
const { tools } = await client.listTools();
console.log(tools.map((t) => t.name));

// Get current war status
const warStatus = await client.callTool({
  name: "get_war_status",
  arguments: {},
});
console.log(warStatus.content[0].text);

// Get details for specific planets by index (up to 5)
const planets = await client.callTool({
  name: "get_planet_details",
  arguments: { planetindices: [57, 153] },
});
console.log(planets.content[0].text);

await client.close();

Without the SDK — raw JSON-RPC over fetch:

async function callTool(name: string, args: Record<string, unknown> = {}) {
  const res = await fetch("https://mcp.avengersofsuperearth.com/mcp", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Accept": "application/json, text/event-stream",
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "tools/call",
      params: { name, arguments: args },
    }),
  });
  const text = await res.text();
  // The response is an SSE frame ("event: message\ndata: {json}\n\n");
  // concatenate its data line(s) to recover the JSON-RPC payload.
  const json = text
    .split("\n")
    .filter((line) => line.startsWith("data:"))
    .map((line) => line.slice(5).trim())
    .join("");
  const data = JSON.parse(json);
  return data.result.content[0].text;
}

const status = await callTool("get_war_status");
const assignments = await callTool("get_assignments");
const dispatches = await callTool("get_dispatches", { limit: 5 });
const planets = await callTool("get_planet_details", { planetindices: [57, 153] });

Python

Using the official MCP Python SDK:

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client("https://mcp.avengersofsuperearth.com/mcp") as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            # Get current war status
            result = await session.call_tool("get_war_status", {})
            print(result.content[0].text)

            # Get details for specific planets by index (up to 5)
            result = await session.call_tool(
                "get_planet_details",
                {"planetindices": [57, 153]},
            )
            print(result.content[0].text)

asyncio.run(main())

Without the SDK — raw JSON-RPC over httpx:

import httpx

MCP_URL = "https://mcp.avengersofsuperearth.com/mcp"

def call_tool(name: str, arguments: dict = {}) -> str:
    payload = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {"name": name, "arguments": arguments},
    }
    headers = {
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
    }
    response = httpx.post(MCP_URL, json=payload, headers=headers)
    response.raise_for_status()
    import json
    # The response is an SSE frame ("event: message\ndata: {json}\n\n");
    # concatenate its data line(s) to recover the JSON-RPC payload.
    text = "".join(
        line[5:].strip()
        for line in response.text.splitlines()
        if line.startswith("data:")
    )
    return json.loads(text)["result"]["content"][0]["text"]

status = call_tool("get_war_status")
assignments = call_tool("get_assignments")
planets = call_tool("get_planet_details", {"planetindices": [57, 153]})

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": "[email protected]"
      }
    }
  }
}

Self-hosted (HTTP server)

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

Development

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

Run a single test file:

npm run 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