Metabase MCP Server

Instructions

Implementation Reference

• src/metabase_mcp_server.py:324-333 (handler)

  The handler function that implements the get_metabase_cards tool. It retrieves all saved questions (cards) from Metabase by making a GET request to the /api/card endpoint. The function is async, takes no parameters, and returns a dictionary containing card metadata including names, IDs, and collections.

  @mcp.tool()
  async def get_metabase_cards() -> Dict[str, Any]:
      """
      Get a list of all saved questions (cards).
  
      Returns:
          Dict[str, Any]: Cards metadata including names, ids, collections.
      """
      logger.info("Getting all cards")
      return await make_metabase_request(RequestMethod.GET, "/api/card")

• src/metabase_mcp_server.py:324-324 (registration)

  The @mcp.tool() decorator registers the get_metabase_cards function as an MCP tool with the FastMCP framework. This decorator is what makes the function available as a tool in the MCP server.

  @mcp.tool()

• src/metabase_mcp_server.py:162-247 (helper)

  Helper function that handles all HTTP requests to the Metabase API. It manages the aiohttp session, handles authentication via API key, implements error handling for connection and response errors, and ensures responses are in dictionary format for FastMCP compatibility. This is used by get_metabase_cards to make the actual API call.

  async def make_metabase_request(
      method: RequestMethod,
      endpoint: str,
      data: Optional[Dict[str, Any] | bytes] = None,
      params: Optional[Dict[str, Any]] = None,
      json: Any = None,
      headers: Optional[Dict[str, str]] = None,
  ) -> Dict[str, Any]:
      """
      Make a request to the Metabase API.
      
      Args:
          method: HTTP method to use (GET, POST, PUT, DELETE)
          endpoint: API endpoint path
          data: Request data (for form data)
          params: URL parameters
          json: JSON request body
          headers: Additional headers
          
      Returns:
          Dict[str, Any]: Response data
          
      Raises:
          MetabaseConnectionError: When the Metabase server is unreachable
          MetabaseResponseError: When Metabase returns a non-2xx status code
          RuntimeError: For other errors
      """
      
      if not METABASE_URL or not METABASE_API_KEY:
          raise RuntimeError("METABASE_URL or METABASE_API_KEY environment variable is not set. Metabase API requests will fail.")
  
      if session is None:
          raise RuntimeError("HTTP session is not initialized. Ensure app_lifespan was called.")
  
      try:
          request_headers = headers or {}
          
          logger.debug(f"Making {method.name} request to {METABASE_URL}{endpoint}")
          
          # Log request payload for debugging (omit sensitive info)
          if json and logger.level <= logging.DEBUG:
              sanitized_json = {**json}
              if 'password' in sanitized_json:
                  sanitized_json['password'] = '********'
              logger.debug(f"Request payload: {sanitized_json}")
              
          response = await session.request(
              method=method.name,
              url=endpoint,
              timeout=aiohttp.ClientTimeout(total=30),
              headers=request_headers,
              data=data,
              params=params,
              json=json,
          )
  
          try:
              # Handle 500 errors with more detailed info
              if response.status >= 500:
                  error_text = await response.text()
                  logger.error(f"Server error {response.status}: {error_text[:200]}")
                  raise MetabaseResponseError(response.status, f"Server Error: {error_text[:200]}", endpoint)
              
              response.raise_for_status()
              response_data = await response.json()
              
              # Ensure the response is a dictionary for FastMCP compatibility
              return ensure_dict_response(response_data)
              
          except aiohttp.ContentTypeError:
              # Handle empty responses or non-JSON responses
              content = await response.text()
              if not content:
                  return {"data": {}}
              logger.warning(f"Received non-JSON response: {content}")
              return {"data": content}
  
      except aiohttp.ClientConnectionError as e:
          logger.error(f"Connection error: {str(e)}")
          raise MetabaseConnectionError("Metabase is unreachable. Is the Metabase server running?") from e
      except aiohttp.ClientResponseError as e:
          logger.error(f"Response error: {e.status}, {e.message}, {e.request_info.url}")
          raise MetabaseResponseError(e.status, e.message, str(e.request_info.url)) from e
      except Exception as e:
          logger.error(f"Request error: {str(e)}")
          raise RuntimeError(f"Request error: {str(e)}") from e