Penpot MCP Server

Instructions

        Args:
            file_id: The ID of the Penpot file
        

Implementation Reference

• penpot_mcp/server/mcp_server.py:204-215 (handler)

  The primary handler function for the MCP 'get_file' tool. It fetches the complete file data from the Penpot API using the provided file_id, caches the result in memory, and returns the data or a formatted error response.

  def get_file(file_id: str) -> dict:
      """Retrieve a Penpot file by its ID and cache it. Don't use this tool for code generation, use 'get_object_tree' instead.
      
      Args:
          file_id: The ID of the Penpot file
      """
      try:
          file_data = self.api.get_file(file_id=file_id)
          self.file_cache.set(file_id, file_data)
          return file_data
      except Exception as e:
          return self._handle_api_error(e)

• penpot_mcp/server/mcp_server.py:188-202 (helper)

  Internal helper function that checks the memory cache first before fetching and caching Penpot file data. Similar to get_file but cache-aware; used by other tools.

  def get_cached_file(file_id: str) -> dict:
      """Internal helper to retrieve a file, using cache if available.
      
      Args:
          file_id: The ID of the Penpot file
      """
      cached_data = self.file_cache.get(file_id)
      if cached_data is not None:
          return cached_data
      try:
          file_data = self.api.get_file(file_id=file_id)
          self.file_cache.set(file_id, file_data)
          return file_data
      except Exception as e:
          return self._handle_api_error(e)

• penpot_mcp/api/penpot_api.py:540-582 (helper)

  Underlying PenpotAPI.get_file method invoked by the MCP tool handler. Sends authenticated POST request to Penpot's /rpc/command/get-file endpoint with the file_id, parses the JSON response, and optionally saves raw or normalized data.

  def get_file(self, file_id: str, save_data: bool = False,
               save_raw_response: bool = False) -> Dict[str, Any]:
      """
      Get details for a specific file.
  
      Args:
          file_id: The ID of the file to retrieve
          features: List of features to include in the response
          project_id: Optional project ID if known
          save_data: Whether to save the data to a file
          save_raw_response: Whether to save the raw response
  
      Returns:
          Dictionary containing file information
      """
      url = f"{self.base_url}/rpc/command/get-file"
  
      payload = {
          "id": file_id,
      }
  
      response = self._make_authenticated_request('post', url, json=payload, use_transit=False)
  
      # Save raw response if requested
      if save_raw_response:
          raw_filename = f"{file_id}_raw_response.json"
          with open(raw_filename, 'w') as f:
              f.write(response.text)
          if self.debug:
              print(f"\nSaved raw response to {raw_filename}")
  
      # Parse JSON
      data = response.json()
  
      # Save normalized data if requested
      if save_data:
          filename = f"{file_id}.json"
          with open(filename, 'w') as f:
              json.dump(data, f, indent=2)
          if self.debug:
              print(f"\nSaved file data to {filename}")
  
      return data

• penpot_mcp/server/mcp_server.py:95-117 (helper)

  Error handling utility used by the get_file tool (and others) to catch exceptions from the API call and return structured error responses, with special handling for CloudFlare protection.

  def _handle_api_error(self, e: Exception) -> dict:
      """Handle API errors and return user-friendly error messages."""
      if isinstance(e, CloudFlareError):
          return {
              "error": "CloudFlare Protection",
              "message": str(e),
              "error_type": "cloudflare_protection",
              "instructions": [
                  "Open your web browser and navigate to https://design.penpot.app",
                  "Log in to your Penpot account", 
                  "Complete any CloudFlare human verification challenges if prompted",
                  "Once verified, try your request again"
              ]
          }
      elif isinstance(e, PenpotAPIError):
          return {
              "error": "Penpot API Error",
              "message": str(e),
              "error_type": "api_error",
              "status_code": getattr(e, 'status_code', None)
          }
      else:
          return {"error": str(e)}