AIPickMyGame

# AIPickMyGame MCP Server > A smart game recommendation system based on Model Context Protocol (MCP): securely synchronize your Epic / GOG / Steam (and GOG Galaxy aggregated multi-platform) game library, automatically complete Chinese metadata, and let AI Agent use natural language to help you answer "What should I play now". ## 1. Why This Project (Pain Points) As is well known, Epic has been giving away free games every week for several years, Steam has many high-quality free small games, and you can also get many Epic and GOG games at a low price through Amazon Prime. As time accumulates, the game library becomes very large (the author currently has **493 games** on Epic). But when it's time to play, it's hard to find what to play: - **Translation chaos**: game names are a mix of Chinese and English, some use development code names, and it's hard to recognize what game it is. - **Weak filtering mechanism**: platform-provided classification and filtering are weak, and it's hard to find what you want to play among hundreds of games. - **Lack of decision support**: there is no ability to recommend based on mood / duration / type, and it's hard to decide what to play when facing a long list. In one sentence: **There are many games, but you don't know what to play**. We need a workflow that can securely obtain the game library, clean up messy data into neat Chinese metadata, and then make precise recommendations through natural language interaction. ## 2. Open-Source Projects Referenced | Project | Reference Points | |------|--------| | [Legendary](https://github.com/derrod/legendary) | A mature Epic Games third-party client. Directly reuse its authentication and game library API to avoid hard-coding Epic OAuth parameters. | | [Heroic Games Launcher](https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher) | ① Login solution: do not hard-code Epic login parameters, but use Legendary's maintained `legendary.gl/epiclogin` auxiliary page to obtain authorizationCode. ② GOG support: replicate its `gogdl` OAuth2 process (client_id/secret, token endpoint, galaxy-library API all public), and implement it with pure Python httpx without introducing binary dependencies. | ## 3. Final Solution Core idea: **Direct domestic connection, no proxy, no root, no reverse engineering**. ``` ┌─────────────────────────────────────────┐ │ AI Agent (Claude Desktop / OpenCode etc.) │ ← Responsible for calling LLM and generating recommendations └──────────────────┬──────────────────────┘ │ MCP Tool Calls (stdio) ▼ ┌─────────────────────────────────────────┐ │ AIPickMyGame MCP Server │ ← Only data processing: no LLM API Key required │ │ │ 1. Authentication synchronization Epic/GOG/Steam/Galaxy multi-platform │ │ 2. Metadata Steam Store (Chinese, direct connection) │ │ 3. Data processing filtering / statistics / formatting │ └─────────────────────────────────────────┘ ``` **Key decisions:** 1. **Authentication and synchronization: four routes to choose from** - Epic uses Legendary, GOG replicates Heroic's gogdl OAuth2, Steam uses official Web API (including playtime), and GOG Galaxy aggregated library can be used to get all platforms at once. All domestic direct connections, login through official/community auxiliary pages, no hard-coded platform parameters. The pros and cons of each route are detailed in [Chapter 5 Comparison Table](#comparison-table). 2. **Metadata main source changed to Steam Store** - Steam store API can be directly connected domestically, and `appdetails` interface can return **Simplified Chinese** type, description, screenshots, cover, and rating. Geographic awareness downgrade chain: - Domestic: **Steam → RAWG (proxy required) → IGDB** - Overseas: RAWG → Steam → IGDB 3. **MCP only processes data, no LLM** - LLM calls are handed over to AI Agent, and this service does not need to configure any model Key, pure local, auditable, and privacy-protected. ## 4. Achieved Effects - ✅ **Fast synchronization**: Legendary direct connection, 493 Epic games synchronized in seconds, no more timeout failures. - ✅ **Multi-platform**: Epic (Legendary), GOG (Galaxy OAuth2), Steam (Web API, including playtime), and can also use GOG Galaxy aggregated library to pull all platforms (Steam/Epic/Uplay/Xbox/Origin) at once. - ✅ **Chinese metadata**: Steam Store returns Simplified Chinese type/description/screenshots/cover/rating. - ✅ **No proxy/root required**: all domestic direct connections. - ✅ **AI recommendations**: natural language "I want to play a relaxing Roguelike this weekend" can get precise recommendations based on your local game library. ## 5. Comparison Table Four synchronization methods have their pros and cons, choose according to your needs: | Method | Command | What you get | Required credentials/preconditions | Playtime | Advantages | Disadvantages | |------|------|----------|----------------|:---:|------|------| | **Epic** | `sync_library("epic")` | All Epic games | Browser login once (authorizationCode) | ❌ | Reuse Legendary, direct connection fast (493 games in seconds); stable login | Only Epic | | **GOG** | `sync_library("gog")` | GOG games | Browser login once (OAuth2) | ❌ | Platform-independent, data clean; pure httpx without binary dependencies | Only GOG games (not including aggregated games from other platforms) | | **Steam** | `sync_library("steam")` | All Steam games you own | Apply Web API Key + SteamID + Profile public | ✅ | **Only can get playtime**; self-contained appid, cover direct connection CDN; no third-party dependency | Need to manually apply Key; Profile must be public | | **Galaxy Aggregated** | `sync_library("galaxy")` | All platform games you bound on GOG Galaxy (Steam/Epic/Uplay/Xbox/Origin…) | Only GOG login required | ❌ | **One login to get all platforms**, including Uplay/Xbox/Origin (469 games tested) | Dependent on your actual binding on GOG Galaxy; no playtime; overlapping data with single-platform synchronization | **How to choose:** - **Only play Epic / only play GOG** → use corresponding single-platform synchronization, cleanest data. - **Heavy Steam user, want to recommend based on "playtime"** → use `steam`, playtime will be included in recommendation summary. - **Multi-platform party, hate logging in one by one** → use `galaxy`, log in once to get all platforms (前提是你平时用 GOG Galaxy 管理各平台). - **Want all platforms and Steam playtime** → `galaxy` + `steam` run once, take what you need by `platform` field. > Metadata completion (`enrich_metadata`) is **通用** for **all platforms**, uniformly using Steam Store Chinese solution, independent of synchronization method. ## 6. How to Use ### 1. Preconditions - Python 3.10+ - `legendary-gl` installed (comes with dependencies) ### 2. Installation ```bash git clone https://github.com/yourusername/AIPickMyGame-MCP.git cd AIPickMyGame-MCP pip install -r requirements.txt ``` ### 3. Configure in AI Agent This service uses **stdio** transmission protocol to interact with AI Agent through inter-process communication, without exposing network ports. **Claude Desktop** - edit `claude_desktop_config.json`: ```json { "mcpServers": { "AIPickMyGame": { "command": "python", "args": ["-m", "mcp_server.main"], "cwd": "/path/to/AIPickMyGame-MCP", "env": { "PYTHONIOENCODING": "utf-8" } } } } ``` **OpenCode** - edit `%USERPROFILE%\.config\opencode\opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "AIPickMyGame": { "type": "local", "command": ["E:/minconda/python.exe", "-m", "mcp_server.main"], "cwd": "d:/AI Coding/xuanyou/AIPickMyGame-MCP", "enabled": true, "environment": { "PYTHONIOENCODING": "utf-8" } } } } ``` > **Windows Notes**: > - Must use Python's **full absolute path** (e.g., `E:/minconda/python.exe`), avoid Windows Store's 0-byte `python.exe` stub causing `EFTYPE` error. > - Must set `PYTHONIOENCODING=utf-8`, otherwise Chinese/emoji will trigger `UnicodeEncodeError`. > - Path建议用 `/` avoid转义. > - OpenCode uses top-level `"mcp"` key (not `"mcpServers"`), `command` is an array, environment variable field name is `"environment"`, modify and **completely restart**. ### 4. First Configure Epic Account In AI Agent, operate in order: 1. **`setup_epic_account()`** - authenticated returns account information; unauthenticated opens browser to `legendary.gl/epiclogin`. 2. In browser, log in to Epic, page displays JSON, copy `authorizationCode`. 3. **`complete_epic_auth("paste code")`** - complete authentication. 4. **`sync_library("epic")`** - synchronize game library to local. 5. **`enrich_metadata("epic", batch_size=15)`** - complete metadata (call multiple times until complete). ### 5. Configure GOG Account (Optional) GOG process similar to Epic: 1. **`setup_gog_account()`** - authenticated returns account information; unauthenticated opens browser to GOG login page. 2. In browser, log in to GOG, successful login page jumps to `embed.gog.com/on_login_success?code=...`. 3. **Copy browser address bar complete URL** (or `code=` value). 4. **`complete_gog_auth("paste URL or code")`** - complete authentication (tool automatically extracts code from URL). 5. **`sync_library("gog")`** - synchronize GOG game library. 6. **`enrich_metadata("gog", batch_size=15)`** - complete metadata (share Steam Chinese solution with Epic). > GOG login page **won't** display code like Epic, code hidden in address bar URL, directly copy whole URL most convenient. ### 6. Configure Steam Account (Optional) Steam synchronization uses official Web API, can get **all owned games + playtime** (playtime useful for recommendations): 1. Apply Web API Key at https://steamcommunity.com/dev/apikey (domain fill `localhost`). 2. Check SteamID64 (17 digits, check at https://steamid.io). 3. Set Steam profile "Game Details" privacy to **public** (otherwise can't pull library). 4. **`setup_steam_account(api_key, steam_id)`** - write configuration. 5. **`sync_library("steam")`** - synchronize game library (including playtime). 6. **`enrich_metadata("steam", batch_size=15)`** - complete Chinese metadata. > Steam games self-contained appid, cover directly use official CDN stitching, no extra request; playtime appears in `smart_recommend` summary, convenient for AI to recommend based on "what you play more". ### 7. One-Click Aggregate Multi-Platform Game Library (Galaxy, Optional) If you bind **GOG Galaxy** with Steam / Epic / Uplay / Xbox / Origin, can log in one GOG account, pull **all-platform** game library at once: 1. Complete GOG authentication above (`setup_gog_account` + `complete_gog_auth`). 2. **`sync_library("galaxy")`** - pull all bound platform games through GOG Galaxy aggregated library, `platform` field marks each game's real source (gog/steam/epic/uplay/...). 3. **`enrich_metadata("galaxy", batch_size=15)`** - complete metadata with Steam Chinese solution. > **Note**: aggregated library depends on your actual binding on GOG Galaxy, how many games you can get depends on your bindings. It overlaps with single-platform `sync_library("epic")`/`"gog"` data, choose according to needs - want "one entry to see all" use `galaxy`, want "platform-independent, clean data" use respective platform synchronization. ### 8. Metadata Configuration (Optional) Edit `config/config.json` `metadata` field: ```json { "metadata": { "provider": "steam", "steam_language": "schinese", "steam_country": "CN", "api_key": "your RAWG_API_KEY (optional for overseas users)", "igdb_client_id": "", "igdb_client_secret": "" } } ``` Domestic users keep default (Steam direct connection Chinese). Overseas users can register RAWG Key at [rawg.io/apidocs](https://rawg.io/apidocs) for free (20,000 requests per month). ### 9. Daily Use Directly chat with AI Agent: ``` User: "I want to play a relaxing Roguelike this weekend" AI: → smart_recommend("epic", "relaxing Roguelike") → Analyze based on your local game library → Return game cards with recommendations ``` Cross-platform recommendation - tell AI "recommend games I bought but haven't played across all platforms": ``` User: "Recommend games I bought but haven't played across all platforms" AI: → smart_recommend("all", "bought but not played") → Merge epic/steam/gog library, each line with [platform] tag → ◆ exact: determine same game (e.g., PAYDAY 2 on epic/steam), directly tell you "this game has X/Y platform versions, choose your version" → ◇ loose: suspected same game (e.g., BioShock 2 Remastered vs BioShock 2), AI judge whether same game; uncertain situations clearly inform user instead of quietly merging. ``` > Cross-platform same game identification adopts "program initial screening + Agent review": program only groups possible same games and marks confidence (exact/loose), final same game judgment and user presentation handed over to AI capable of understanding semantics, uncertain situations clearly inform user instead of quietly merging. ## Tool List | Tool | Parameters | Description | |------|------|------| | `setup_epic_account()` | None | Checks Legendary authentication status, opens browser for login if not authenticated | | `complete_epic_auth(code)` | `authorization_code: str` | Completes Epic authentication using authorization code | | `setup_gog_account()` | None | Checks GOG authentication status, opens browser for login if not authenticated | | `complete_gog_auth(code)` | `authorization_code: str` | Completes GOG authentication using authorization code or login redirect URL | | `setup_steam_account(api_key, steam_id)` | `api_key: str`, `steam_id: str` | Configures Steam Web API credentials (writes to config) | | `sync_library(platform, force)` | `platform="epic"`, `force=false` | Synchronizes game library to local (Epic→Legendary, GOG→Galaxy API, Steam→Web API, Galaxy→all-platform aggregated library) | | `enrich_metadata(platform, batch_size)` | `platform="epic"`, `batch_size=50` | Completes game metadata (rating, genre, description, screenshots), supports batching | | `get_user_library(platform)` | `platform="epic"` | Retrieves synchronized game library data | | `list_games(platform, genre, search)` | Optional filter parameters | Lists and filters games | | `format_games_for_llm(platform, query, max_games)` | Formatting parameters | Formats game data into LLM prompt | | `smart_recommend(platform, query, max_desc_len)` | Recommendation parameters | Returns compact library summary (name\|genre\|rating\|year\|tags\|description, Steam library includes playtime). `platform="all"` enables cross-platform mode: merges Epic/Steam/GOG, labels each game's platform, and performs initial screening for duplicates (◆exact match / ◇loose match requiring Agent rejudgment) for LLM deep analysis | --- ## Project Structure ``` AIPickMyGame-MCP/ ├── mcp_server/ # MCP Server core │ ├── main.py # FastMCP entry point, defines all tools │ ├── config.py # Configuration management (Pydantic) │ ├── auth/ # Authentication (Epic→Legendary, GOG→OAuth2) │ ├── sync/ # Game library synchronization (legendary / gog / steam / galaxy aggregated) │ ├── metadata/ # Metadata completion (Steam primary source + RAWG/IGDB fallback) │ ├── recommend/ # Game library data processing (filtering/statistics/formatting) │ └── storage/ # Token and game library cache ├── browser-extension/ # Browser extension (alternative data extraction scheme) ├── config/ # Configuration files and token storage └── requirements.txt # Python dependencies ``` ### Data Flow ``` Authentication → Synchronization → Completion → Recommendation │ │ │ │ │ │ │ └─ smart_recommend: Full library summary (including playtime) → AI Agent LLM analysis │ │ └─ enrich_metadata: Steam (Chinese) → RAWG → IGDB fallback (all-platform universal) │ └─ sync_library: Epic/GOG/Steam/Galaxy → local JSON └─ setup_*_account: Epic/GOG browser login, Steam API key entry ``` --- ## Architecture and FAQ **MCP Server does not call LLM.** It only reads and processes data, passing structured game libraries to AI Agents, which use their own LLMs for recommendations. Therefore, **no model API Key is required**. | Question | Answer | |------|------| | Where are tokens stored? | JSON files in `config/tokens/` directory. Using files instead of system keychains because Epic's refresh token may exceed Windows Credential Manager's 512-byte limit | | What if authentication fails? | Delete `config/tokens/epic_token.json` or run `legendary auth --delete`, then re-run `setup_epic_account()` | | Do I need an LLM API Key? | No, LLM calls are handled by AI Agents | | How do I switch Epic accounts? | Run `legendary auth --delete` to log out, then re-authenticate | | Why can't I pull Steam games? | Ensure ① API key is correct ② SteamID64 is correct ③ profile's "Game Details" is set to **public** (all three are required) | | Why does Steam Key application fail? | Account needs some consumption history/phone token binding; if still fails, use `sync_library("galaxy")` to indirectly get Steam library from GOG (without playtime) | | Will API Keys be leaked? | Keys and tokens are stored in `config/config.json` and `config/tokens/`, excluded by `.gitignore` and not committed to the repository | | Why is metadata completion slow/failing? | Steam has IP-level rate limiting; reduce `batch_size` for batch completion; ensure no system proxy interference (this service has forced direct connection to Steam) | | Why are recommended results in English? | Game library titles are mostly in English (Epic/Steam/GOG sources don't provide Chinese titles, about 95% are English). `smart_recommend` includes instructions for Agents: present recommendations with Chinese translations in parentheses if available (e.g., `Vampire Survivors（吸血鬼幸存者）`), otherwise keep original titles. Whether to label Chinese titles is decided by the Agent's LLM | | Will re-synchronization lose completed metadata? | No. `sync_library` fetches the latest game list from the platform API and fills in existing local library fields (rating/genre/description/tags/`_meta_source` etc.) based on `app_name`, so metadata is not lost. `enrich_metadata` is also incremental: games with existing `_meta_source` (steam/rawg/igdb) and certain fields are skipped, only incomplete ones are supplemented. Metadata is persisted with the library JSON (`~/Games/{platform}_library.json`) without independent cache files | --- ## Development ```bash pytest # Run tests python verify_setup.py # Verify project structure ``` ## License MIT License — see [LICENSE](LICENSE) file. Copyright (c) 2026 Hsia97