custom_query
Run a custom Apicalypse query against any IGDB API endpoint
LABSCO SUMMARY
Three shaped tools for the common asks, and a raw query escape hatch for everything else.
Search, details and anticipated-games cover most questions; custom_query plus the two syntax resources is what lets an agent answer things like "RPGs rated above 90" without waiting for a new tool. One caution the README states plainly: IGDB allows four requests per second and this server does not rate-limit, so rapid-fire querying is on you.
What it is
A FastMCP server over the IGDB API v4. It handles the Twitch OAuth exchange and caches the token, so you work in games rather than in authentication, and it leaves the full Apicalypse query language available when the shaped tools are not enough.
What you get
- Games searched by name, with the fields and result count you ask for, from 1 to 500 —
search_games - Full detail on one title by its IGDB id, covering ratings, platforms, developers and DLC —
get_game_details - Upcoming games ranked by hype, with a
min_hypesfloor —get_most_anticipated_games - Any IGDB endpoint queried directly in Apicalypse, for filters the shaped tools do not cover —
custom_query - Two reference resources for writing those queries:
igdb://endpointsandigdb://query-syntax - Three ready-made prompts:
search_game,game_details,most_anticipated
Requirements
A Twitch account and an application registered in the Twitch Developer Console, giving you IGDB_CLIENT_ID and IGDB_CLIENT_SECRET. Python 3.12 or newer, run through uvx straight from the repository, or installed via Smithery. Token refresh is handled for you.
Setup effort
One command plus credentials — npx -y @smithery/cli install @bielacki/igdb-mcp-server, then supply credentials
USE CASES
01
Finding a game and everything attached to it
Search by name to get the id, then pull full details — ratings, platforms, developers, DLC and expansions come back in one call.
02
Tracking what the audience is waiting for
List upcoming titles ordered by hype with a minimum hype count, to separate genuinely awaited releases from the long tail of announced ones.
03
Asking a question the shaped tools do not cover
Read the endpoint list and syntax reference, then send an Apicalypse query — filter by rating, studio, genre or release window in a single request rather than several.
4 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
get_game_details
Retrieve detailed information about a specific game from IGDB
get_most_anticipated_games
Fetch upcoming games sorted by hype count, filtered for future or TBA releases
search_games
Search for games in the IGDB database
BEFORE YOU INSTALL
What to know first
Tools you get
4 tools when we connected. All four tools read. custom_query accepts a raw Apicalypse query against any IGDB endpoint; search_game, game_details and most_anticipated are prompts, not tools.
Requires
- IGDB_CLIENT_ID in your environment
- IGDB_CLIENT_SECRET in your environment
CONTEXT COST
Light Standing cost
Rated by the size of the 4 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
Any MCP client — Smithery
TERMINAL
npx -y @smithery/cli install @bielacki/igdb-mcp-serverMCP Clients
Any MCP client — uvx
ANY MCP CLIENT — UVX · JSON
{
"mcpServers": {
"igdb-mcp": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/bielacki/igdb-mcp-server.git",
"igdb-mcp-server"
],
"env": {
"IGDB_CLIENT_ID": "<YOUR_IGDB_CLIENT_ID>",
"IGDB_CLIENT_SECRET": "<YOUR_IGDB_CLIENT_SECRET>"
}
}
}
}
