npm package: @godsandmortals/mcp-server
Description: MCP server for Gods & Mortals game API — expose game actions as tools for AI agents
Author: GodsAndMortals
Latest version: 0.1.0

# @godsandmortals/mcp-server

MCP server for Gods & Mortals game API. Exposes game actions as MCP tools so any compatible AI agent (Claude Desktop, Claude Code, etc.) can play the game on your behalf.

## Installation

```bash
npm install -g @godsandmortals/mcp-server
```

Or use directly with `npx` (no install required):

```bash
npx @godsandmortals/mcp-server
```

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `GODSX_API_URL` | Yes | — | Base URL of the GodsXMortals game API (e.g. `https://app.roolzgods.com`) |
| `GODSX_AGENT_TOKEN` | Yes | — | Agent bearer token (`gxm_agent_...`) obtained from the game's Agent Access screen |
| `GODSX_POLL_INTERVAL_MS` | No | `30000` | Polling interval for async operations (training, investments) in milliseconds |
| `GODSX_REQUEST_TIMEOUT_MS` | No | `10000` | HTTP request timeout in milliseconds |

## Obtaining a Token

1. Open the game in Telegram
2. Go to **Profile → Settings → Agent Access**
3. Click **Create New Token**
4. Copy the token immediately — it is shown only once

## Usage with Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gods-and-mortals": {
      "command": "npx",
      "args": ["-y", "@godsandmortals/mcp-server"],
      "env": {
        "GODSX_API_URL": "https://app.roolzgods.com",
        "GODSX_AGENT_TOKEN": "gxm_agent_your_token_here"
      }
    }
  }
}
```

Restart Claude Desktop. Claude will now have access to all game tools.

## Usage with Claude Code

Add the MCP server to your Claude Code project configuration or use it directly from the CLI:

```bash
GODSX_AGENT_TOKEN=gxm_agent_... GODSX_API_URL=https://app.roolzgods.com npx @godsandmortals/mcp-server
```

## Available Tools

### Status (8 tools)
- `get_player_status` — Full player state (stats, gold, level, class, kingdom, guild)
- `get_round_info` — Current round info (TC day, phase, active status)
- `get_active_events` — Currently active game events with modifiers
- `get_leaderboard` — Player/kingdom/guild rankings
- `get_buildings_status` — Buildings, companions, lab, dock status
- `get_tavern_status` — Stamina, tickets, addiction level
- `get_inventory` — Items, equipment, potions
- `get_daily_mission` — Current daily mission progress

### Combat (14 tools)
- `perform_heist` / `bulk_heist` — Solo and stamina-burning heist runs
- `assault_player` — Attack another player for stats and respect
- `start_sabotage` — Deploy sabotage agents
- `join_raid` / `get_raid_list` — Guild raid management
- `bribe_jail` / `bribe_hospital` — Early release via gold bribe
- `enter_hunting_grounds` — Hunt in the wilderness
- `use_mercenary` — Hire mercenaries for heists
- `check_assault_targets` — Find optimal PvP targets
- `get_jail_status` / `get_hospital_status` — Current confinement info

### Economy (17 tools)
- `bank_deposit` / `bank_withdraw` — Gold banking
- `collect_buildings` / `upgrade_building` / `buy_building_slot` / `build_new` — Building management
- `collect_companions` / `buy_companions` — Companion operations
- `invest_gold` / `collect_investment` — Investment management
- `buy_drugs` / `sell_drugs_docks` / `sell_drugs_dealer` / `get_drug_prices` — Drug trading
- `get_dock_ships` — Shipping routes
- `buy_shop_item` — Purchase shop items
- `craft_potion` — Brew potions in the lab

### Casino (6 tools)
- `roll_dice` — Dice game
- `play_blackjack` / `blackjack_action` — Blackjack session
- `play_slots` — Slot machine
- `buy_lottery_ticket` — Lottery
- `refill_stamina` — Tavern stamina refill (tracks addiction)

### Social (12 tools)
- `join_kingdom` / `create_guild` / `join_guild` / `get_guild_info` — Kingdom and guild management
- `donate_to_guild` — Donate gold for respect points
- `start_guild_war` — Declare war on another guild
- `join_divine_trial` — Enter the Divine Trial arena
- `conquer_district` / `challenge_district` — District takeover
- `call_mule` — Call a divine mule for item pickup
- `become_blessed` — Seek divine blessing
- `send_chat` — Post in kingdom or guild chat

### Management (14 tools)
- `start_training` / `collect_training` / `start_advanced_training` / `get_training_status` — Stat training
- `equip_item` / `unequip_item` — Equipment management
- `upgrade_lab` / `queue_potion` — Laboratory operations
- `hire_guard` / `fire_guard` — Hire personal guards
- `start_academy_course` — Academy courses
- `claim_mission_reward` — Claim completed daily mission
- `claim_badge` — Claim badge rewards
- `change_class` — Switch player class

## MCP Resources

| URI | Description |
|---|---|
| `godsx://player/{playerId}/state` | Full player state |
| `godsx://round/current` | Current round info |
| `godsx://leaderboard/{type}` | Rankings (respect/kills/wealth/guild) |
| `godsx://events/active` | Active game events |
| `godsx://kingdom/{kingdomId}/rankings` | Kingdom standings |

## Configuration Example

```json
{
  "mcpServers": {
    "gods-and-mortals": {
      "command": "npx",
      "args": ["-y", "@godsandmortals/mcp-server"],
      "env": {
        "GODSX_API_URL": "https://app.roolzgods.com",
        "GODSX_AGENT_TOKEN": "gxm_agent_a1b2c3d4e5f6...",
        "GODSX_POLL_INTERVAL_MS": "15000",
        "GODSX_REQUEST_TIMEOUT_MS": "10000"
      }
    }
  }
}
```