@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

npm install -g @godsandmortals/mcp-server

Or use directly with npx (no install required):

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:

{
  "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:

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

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