game MCP server
Commit Oct 31, 2026Lets an AI client act as a game engine for a text-based RPG through interactive tool calls and narration.
Also known as shaneguo89757/game-server
- Stars
- 0
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 31, 2026
- License
- MIT
What is game MCP?
game lets an AI client act as a game engine for a text-based RPG through interactive tool calls and narration. It exposes 8 tools, such as login, roster, character.
Summary generated from the project's README
About game MCP server
Playing a text-based RPG directly within your AI chat interface is what this server enables. Instead of the AI simply assisting you, it acts as the game engine, using tool calls to process actions and narration to describe the results. This setup allows users to engage in turn-based combat, explore world maps, and interact with NPCs without leaving clients like Claude Desktop, Claude Code, or claude.ai.
Users connect to a remote instance using GitHub OAuth for authentication, which serves as their player identity. The server manages persistent character progress through a PostgreSQL database and offers distinct classes such as Warrior, Mage, and Archer. The game mechanics include a rare item system with a global supply cap, turn-based battles with status effects like poison or freeze, and various tools for managing inventory, movement, and character rosters. It is designed for anyone who wants to transform their AI terminal into an interactive gaming environment.
What you can do with it
- 1Start a new adventureAsk the AI to begin a session to initialize your character and enter the game world.
- 2Engage in turn-based combatDirect the AI to use specific skills or flee during a battle encounter.
- 3Explore the game worldNavigate between different locations on the map to find enemies or new areas.
Written from the project's README. Every use case is checked against a quote from it.
game MCP tools 8
Detected from the READMEloginrostercharactermapbattlenpcinventoryhistory
Configuration
BASE_URLDATABASE_URLGITHUB_CLIENT_IDGITHUB_CLIENT_SECRETMCP_TRANSPORT
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableshaneguo89757/game-server is public and reachablegithub.com/shaneguo89757/game-server ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-31github.com/shaneguo89757/game-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model8 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMCP Game Server
A text-based RPG designed to be played through Model Context Protocol (MCP). Claude — or any MCP-compatible AI — acts as the game engine: every game action is a tool call, and the AI narrates the results.
login → roster → character → map → battle → npc → inventory → history
Status: Early development. Game content and APIs may change between versions.
Why this project exists
I spend most of my workday talking to Claude. At some point I thought — what if it could also entertain me?
Not "AI plays the game for me." That's boring. I wanted to play, just without leaving my AI client to do it.
The problem: no graphics, no GPU, no game loop. Just tokens coming back from an API. So I leaned into it — the AI doesn't assist the game, it is the game. Raw JSON goes in, and Claude turns it into a dungeon, a fight, a merchant who overcharges you. The language model that writes your PRs now narrates your death by goblin.
MCP fit because it's already everywhere. Claude Desktop, Claude Code, claude.ai — pick one, connect, play. No extra app. No signup. Works wherever you already are.
I built this for fun. But I also built it because I think AI service is becoming the new user terminal — and there's a whole category of things that only make sense now that AI has a protocol. Nobody's explored much of it yet. This is one small corner of that space.
Maybe it makes you want to play. Maybe it makes you want to build something weirder. Either outcome is fine with me.
Play now
A public instance is running at https://game.siandesign.org. You'll need a GitHub account — it's used for authentication and as your player identity.
Connect once, and GitHub OAuth handles login automatically. No API key, no separate signup.
Claude Code CLI
Add to your ~/.claude.json under mcpServers:
"game-server": {
"type": "http",
"url": "https://game.siandesign.org/mcp"
}
Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"game-server": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://game.siandesign.org/mcp"]
}
}
}
claude.ai
Go to Settings → Integrations → Add custom integration and enter:
https://game.siandesign.org/mcp
For the best experience, create a Project in claude.ai and add this to the project instructions:
When presenting choices to the player, always use the `ask_user_input_v0` tool to display options as interactive UI — never list them as plain text.
This enables the interactive choice UI instead of text-only responses.
On first connection, your MCP client will open a browser window to complete GitHub login. After that, the session token is cached automatically.
Then just tell Claude:
"Let's play the game." or "Game Start"
Features
- Turn-based combat — skills, status effects (poison, freeze, guard), exp/gold rewards, level-up
- Three character classes — Warrior, Mage, Archer, each with unique skill sets
- World map — four locations with exits, enemies, and random ambushes on movement
- NPC interactions — dialogue, shops, inn rest
- Rare item system — world-limited items with a global supply cap enforced at drop time
- Persistent state — all character progress written to PostgreSQL in real time
- GitHub OAuth — your GitHub account is your player account; no passwords stored
MCP Tools
| Tool | Actions | Requires auth |
|---|---|---|
login |
— | OAuth token identity |
roster |
list · templates · create |
character ownership |
character |
status |
character ownership |
map |
overview · location · move |
move requires ownership |
battle |
start · skill · flee |
character ownership |
npc |
touch · talk · shop · rest · buy |
rest/buy require ownership |
inventory |
use |
character ownership |
history |
recent · important |
character ownership |
map/overview, map/location, npc/touch, npc/talk, npc/shop are public — no character needed.
Self-host
Stack: Node.js 22 · TypeScript · PostgreSQL · Drizzle ORM · GitHub OAuth — see docs/architecture.md for the full breakdown.
Prerequisites
- Node.js 22+
- PostgreSQL 14+
- A GitHub OAuth App
Setup
git clone https://github.com/shaneguo89757/game-server.git
cd game-server
npm install
Create .env.local:
DATABASE_URL=postgresql://user:password@localhost:5432/game_server
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
BASE_URL=http://localhost:3000
PORT=3000
MCP_TRANSPORT=http
Create your GitHub OAuth App at Settings → Developer settings → OAuth Apps. Set the callback URL to http://localhost:3000/oauth/callback.
createdb game_server # if the database does not exist yet
npm run migrate # applies all pending SQL migrations
npm run dev # development server (ts-node, no build step)
Never commit
.env.local. It is listed in.gitignore.
Architecture
The server is layered so that game logic never touches the database directly:
MCP Client → mcp/tools/* → game/* → repository/* → db/*
game/* functions receive a repos: Repos interface and never import from db/*. This boundary is enforced by ESLint and makes unit testing trivial — FakePlayerScope implements Repos in memory with no mocking needed.
Full architecture details, deployment instructions, and a guide to extending game content: docs/architecture.md.
Running tests
npm test # run once
npm run test:watch # watch mode
Tests use FakePlayerScope — an in-memory implementation of the Repos interface. No database or network connection required.
Contributing
Contributions are welcome — whether that's new enemies, items, skills, bug fixes, or architectural improvements.
Before opening a PR:
npx tsc --noEmit # type check
npm run lint # architecture + style rules
npm test # unit tests
Guidelines:
game/*must not import fromdb/*orrepository/*. ESLint will catch violations.- New game logic should have unit tests using
FakePlayerScope(seetest/game/for examples). - New MCP tools go in
src/mcp/tools/, business logic insrc/game/, DB access insrc/repository/. - Migrations are hand-written SQL in
drizzle/— nodrizzle-kitcommands.
License
game MCP questions
What tools does game MCP provide?
It exposes 8 tools, including login, roster, character, map, battle.
How do I play the game?
You can connect via Claude Desktop, Claude Code, or claude.ai and simply tell the AI, "Let's play the game."
Do I need to create a new account to play?
No, the game uses your existing GitHub account for authentication and player identity via OAuth.
What character classes are available?
The game features three unique classes: Warrior, Mage, and Archer.
Is my game progress saved?
Yes, all character progress is written to a PostgreSQL database in real time to ensure persistent state.