custom_query
Execute custom Apicalypse queries to retrieve specific video game data from IGDB endpoints like games, companies, or platforms.
Instructions
Run a custom Apicalypse query against any IGDB API endpoint
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| endpoint | Yes | The API endpoint to query (e.g., 'games', 'companies', 'platforms', 'people', 'characters') | |
| query | Yes | The Apicalypse query string |
Implementation Reference
- src/igdb_mcp_server/server.py:276-306 (handler)The handler function that executes the custom_query tool. It accepts an endpoint and Apicalypse query, retrieves the IGDB client, and performs the API request.async def custom_query( endpoint: Annotated[ str, Field( description="The API endpoint to query (e.g., 'games', 'companies', 'platforms', 'people', 'characters')" ), ], query: Annotated[str, Field(description="The Apicalypse query string")], ctx: Context, ) -> List[Dict[str, Any]]: """ Execute a custom IGDB API query. This allows advanced users to write their own IGDB queries using the Apicalypse query language. See https://api-docs.igdb.com/#apicalypse for query syntax. Args: endpoint: The API endpoint to query (e.g., "games", "companies", "platforms") query: The Apicalypse query string ctx: Context for accessing session configuration Returns: Raw response from the IGDB API Example: endpoint: "games" query: "fields name,rating; where rating > 90; sort rating desc; limit 5;" """ igdb_client = get_igdb_client(ctx) return await igdb_client.make_request(endpoint, query)
- src/igdb_mcp_server/server.py:271-275 (registration)The @mcp.tool decorator that registers the custom_query tool with the FastMCP server.@mcp.tool( name="custom_query", title="Custom IGDB Query", description="Run a custom Apicalypse query against any IGDB API endpoint" )
- Pydantic schema definitions for the input parameters of the custom_query tool using Annotated and Field.endpoint: Annotated[ str, Field( description="The API endpoint to query (e.g., 'games', 'companies', 'platforms', 'people', 'characters')" ), ], query: Annotated[str, Field(description="The Apicalypse query string")], ctx: Context, ) -> List[Dict[str, Any]]:
- The IGDBClient.make_request method used by custom_query to perform the actual API call.async def make_request(self, endpoint: str, query: str) -> List[Dict[str, Any]]: """Make a request to the IGDB API.""" token = await self.get_access_token() response = await self.http_client.post( f"{IGDB_BASE_URL}/{endpoint}", headers={ "Client-ID": self.client_id, "Authorization": f"Bearer {token}", "Accept": "application/json", }, content=query, timeout=30.0, ) response.raise_for_status() data = response.json() if isinstance(data, list): return data return [data]
- Helper function to get or initialize the IGDBClient instance, called by custom_query.def get_igdb_client(ctx: Optional[Context] = None) -> IGDBClient: """Get or create the IGDB client singleton.""" global _igdb_client if "_igdb_client" not in globals(): # Get credentials from environment variables or Smithery settings # Check if context has session_config (Smithery mode) settings = getattr(ctx, 'session_config', None) if ctx else None client_id = os.getenv("IGDB_CLIENT_ID") or (settings.IGDB_CLIENT_ID if settings else None) client_secret = os.getenv("IGDB_CLIENT_SECRET") or (settings.IGDB_CLIENT_SECRET if settings else None) if not client_id or not client_secret: raise ValueError( "Please set IGDB_CLIENT_ID and IGDB_CLIENT_SECRET. " "You can either set them as environment variables or configure them in Smithery. " "You can obtain these from https://api-docs.igdb.com/#account-creation" ) _igdb_client = IGDBClient(client_id, client_secret) return _igdb_client