IGDB MCP Server

Instructions

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"
  )

• src/igdb_mcp_server/server.py:277-285 (schema)

  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]]:

• src/igdb_mcp_server/server.py:104-124 (helper)

  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]

• src/igdb_mcp_server/server.py:130-152 (helper)

  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