Metabase MCP Server

Instructions

Implementation Reference

• src/metabase_mcp_server.py:687-698 (handler)

  The main handler function for the 'get_dashboard_by_id' tool. It takes a dashboard_id parameter and makes a GET request to the Metabase API endpoint /api/dashboard/{dashboard_id}, returning dashboard metadata including id, name, cards, and tabs.

  async def get_dashboard_by_id(dashboard_id: int) -> Dict[str, Any]:
      """
      Get a dashboard by ID.
  
      Args:
          dashboard_id (int): ID of the dashboard.
  
      Returns:
          Dict[str, Any]: Dashboard metadata including id, name, cards, and tabs.
      """
      logger.info(f"Getting dashboard {dashboard_id}")
      return await make_metabase_request(RequestMethod.GET, f"/api/dashboard/{dashboard_id}")

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

  The @mcp.tool() decorator registers the get_dashboard_by_id function as an MCP tool, making it available to MCP clients.

  @mcp.tool()

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

  The make_metabase_request helper function handles all HTTP communication with the Metabase API. It constructs and executes HTTP requests with proper error handling, authentication, and logging.

  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:

• src/models/dashboard_card.py:1-26 (schema)

  Schema definition for DashboardCard model, representing a card within a Metabase dashboard with attributes like id, card_id, position (row, col), size (size_x, size_y), and parameter mappings.

  from dataclasses import dataclass, field
  from typing import List, Dict, Any
  
  @dataclass
  class DashboardCard:
      """
      Represents a card within a Metabase dashboard.
      
      Attributes:
          id (int): Use negative numbers to auto generate the ids 
              or use any unique value but,
              it must be unique within the dashboard
          card_id (int): The ID of the card/visualization
          row (int): The row position in the dashboard grid
          col (int): The column position in the dashboard grid
          size_x (int): The width of the card in grid units
          size_y (int): The height of the card in grid units
          parameter_mappings (List[Dict[str, Any]]): Parameter mappings for the card
      """
      id: int  # Use negative numbers to auto generate the ids
      card_id: int
      row: int
      col: int
      size_x: int
      size_y: int
      parameter_mappings: List[Dict[str, Any]] = field(default_factory=list)

• src/models/dashboard_tab.py:1-14 (schema)

  Schema definition for DashboardTab model, representing a tab within a Metabase dashboard with id and name attributes.

  from dataclasses import dataclass
  from typing import Optional
  
  @dataclass
  class DashboardTab:
      """
      Represents a tab within a Metabase dashboard.
      
      Attributes:
          id (Optional[int]): The tab ID, optional for new tabs
          name (str): The name of the tab
      """
      id: Optional[int] = None
      name: str = ""