Penpot MCP Server

Instructions

        Args:
            file_id: The ID of the Penpot file
            page_id: The ID of the page containing the object
            object_id: The ID of the object to export
            export_type: Image format (png, svg, etc.)
            scale: Scale factor for the exported image
        

Implementation Reference

• penpot_mcp/server/mcp_server.py:216-269 (handler)

  The primary handler function for the 'export_object' MCP tool. It orchestrates the export by calling the PenpotAPI.export_and_download method, handles temporary files, creates an MCP Image object, and optionally serves the image via HTTP.

  @self.mcp.tool()
  def export_object(
          file_id: str,
          page_id: str,
          object_id: str,
          export_type: str = "png",
          scale: int = 1) -> Image:
      """Export a Penpot design object as an image.
      
      Args:
          file_id: The ID of the Penpot file
          page_id: The ID of the page containing the object
          object_id: The ID of the object to export
          export_type: Image format (png, svg, etc.)
          scale: Scale factor for the exported image
      """
      temp_filename = None
      try:
          import tempfile
          temp_dir = tempfile.gettempdir()
          temp_filename = os.path.join(temp_dir, f"{object_id}.{export_type}")
          output_path = self.api.export_and_download(
              file_id=file_id,
              page_id=page_id,
              object_id=object_id,
              export_type=export_type,
              scale=scale,
              save_to_file=temp_filename
          )
          with open(output_path, "rb") as f:
              file_content = f.read()
              
          image = Image(data=file_content, format=export_type)
          
          # If HTTP server is enabled, add the image to the server
          if self.image_server and self.image_server.is_running:
              image_id = hashlib.md5(f"{file_id}:{page_id}:{object_id}".encode()).hexdigest()
              # Use the current image_server_url to ensure the correct port
              image_url = self.image_server.add_image(image_id, file_content, export_type)
              # Add HTTP URL to the image metadata
              image.http_url = image_url
              
          return image
      except Exception as e:
          if isinstance(e, CloudFlareError):
              raise Exception(f"CloudFlare Protection: {str(e)}")
          else:
              raise Exception(f"Export failed: {str(e)}")
      finally:
          if temp_filename and os.path.exists(temp_filename):
              try:
                  os.remove(temp_filename)
              except Exception as e:
                  print(f"Warning: Failed to delete temporary file {temp_filename}: {str(e)}")

• penpot_mcp/api/penpot_api.py:771-816 (helper)

  Core helper method 'export_and_download' in PenpotAPI class that handles the actual Penpot API interactions: creates an export job and downloads the resulting image file.

  def export_and_download(self, file_id: str, page_id: str, object_id: str,
                          save_to_file: Optional[str] = None, export_type: str = "png",
                          scale: int = 1, name: str = "Board", suffix: str = "",
                          email: Optional[str] = None, password: Optional[str] = None,
                          profile_id: Optional[str] = None) -> Union[bytes, str]:
      """
      Create and download an export in one step.
  
      This is a convenience method that combines create_export and get_export_resource.
  
      Args:
          file_id: The file ID
          page_id: The page ID
          object_id: The object ID to export
          save_to_file: Path to save the file (if None, returns the content)
          export_type: Type of export (png, svg, pdf)
          scale: Scale factor for the export
          name: Name for the export
          suffix: Suffix to add to the export name
          email: Email for authentication (if different from instance)
          password: Password for authentication (if different from instance)
          profile_id: Optional profile ID (if not provided, will be fetched automatically)
  
      Returns:
          Either the file content as bytes, or the path to the saved file
      """
      # Create the export
      resource_id = self.create_export(
          file_id=file_id,
          page_id=page_id,
          object_id=object_id,
          export_type=export_type,
          scale=scale,
          email=email,
          password=password,
          profile_id=profile_id
      )
  
      # Download the resource
      return self.get_export_resource(
          resource_id=resource_id,
          save_to_file=save_to_file,
          email=email,
          password=password
      )

• penpot_mcp/api/penpot_api.py:584-671 (helper)

  Supporting helper 'create_export' that sends the Transit+JSON payload to Penpot's /export endpoint to initiate the object export job.

  def create_export(self, file_id: str, page_id: str, object_id: str,
                    export_type: str = "png", scale: int = 1,
                    email: Optional[str] = None, password: Optional[str] = None,
                    profile_id: Optional[str] = None):
      """
      Create an export job for a Penpot object.
  
      Args:
          file_id: The file ID
          page_id: The page ID
          object_id: The object ID to export
          export_type: Type of export (png, svg, pdf)
          scale: Scale factor for the export
          name: Name for the export
          suffix: Suffix to add to the export name
          email: Email for authentication (if different from instance)
          password: Password for authentication (if different from instance)
          profile_id: Optional profile ID (if not provided, will be fetched automatically)
  
      Returns:
          Export resource ID
      """
      # This uses the cookie auth approach, which requires login
      token = self.login_for_export(email, password)
  
      # If profile_id is not provided, get it from instance variable
      if not profile_id:
          profile_id = self.profile_id
  
      if not profile_id:
          raise ValueError("Profile ID not available. It should be automatically extracted during login.")
  
      # Build the URL for export creation
      url = f"{self.base_url}/export"
  
      # Set up the data for the export
      payload = {
          "~:wait": True,
          "~:exports": [
              {"~:type": f"~:{export_type}",
               "~:suffix": "",
               "~:scale": scale,
               "~:page-id": f"~u{page_id}",
               "~:file-id": f"~u{file_id}",
               "~:name": "",
               "~:object-id": f"~u{object_id}"}
          ],
          "~:profile-id": f"~u{profile_id}",
          "~:cmd": "~:export-shapes"
      }
  
      if self.debug:
          print("\nCreating export with parameters:")
          print(json.dumps(payload, indent=2))
  
      # Create a session with the auth token
      export_session = requests.Session()
      export_session.cookies.set("auth-token", token)
  
      headers = {
          "Content-Type": "application/transit+json",
          "Accept": "application/transit+json",
          "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
      }
  
      # Make the request
      response = export_session.post(url, json=payload, headers=headers)
  
      if self.debug and response.status_code != 200:
          print(f"\nError response: {response.status_code}")
          print(f"Response text: {response.text}")
  
      response.raise_for_status()
  
      # Parse the response
      data = response.json()
  
      if self.debug:
          print("\nExport created successfully")
          print(f"Response: {json.dumps(data, indent=2)}")
  
      # Extract and return the resource ID
      resource_id = data.get("~:id")
      if not resource_id:
          raise ValueError("Resource ID not found in response")
  
      return resource_id

• penpot_mcp/api/penpot_api.py:672-770 (helper)

  Supporting helper 'get_export_resource' that polls/retrieves the exported image content from Penpot using the resource ID.

  def get_export_resource(self,
                          resource_id: str,
                          save_to_file: Optional[str] = None,
                          email: Optional[str] = None,
                          password: Optional[str] = None) -> Union[bytes,
                                                                   str]:
      """
      Download an export resource by ID.
  
      Args:
          resource_id: The resource ID from create_export
          save_to_file: Path to save the file (if None, returns the content)
          email: Email for authentication (if different from instance)
          password: Password for authentication (if different from instance)
  
      Returns:
          Either the file content as bytes, or the path to the saved file
      """
      # This uses the cookie auth approach, which requires login
      token = self.login_for_export(email, password)
  
      # Build the URL for the resource
      url = f"{self.base_url}/export"
  
      payload = {
          "~:wait": False,
          "~:cmd": "~:get-resource",
          "~:id": resource_id
      }
      headers = {
          "Content-Type": "application/transit+json",
          "Accept": "*/*",
          "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
      }
      if self.debug:
          print(f"\nFetching export resource: {url}")
  
      # Create a session with the auth token
      export_session = requests.Session()
      export_session.cookies.set("auth-token", token)
  
      # Make the request
      response = export_session.post(url, json=payload, headers=headers)
  
      if self.debug and response.status_code != 200:
          print(f"\nError response: {response.status_code}")
          print(f"Response headers: {response.headers}")
  
      response.raise_for_status()
  
      # Get the content type
      content_type = response.headers.get('Content-Type', '')
  
      if self.debug:
          print(f"\nResource fetched successfully")
          print(f"Content-Type: {content_type}")
          print(f"Content length: {len(response.content)} bytes")
  
      # Determine filename if saving to file
      if save_to_file:
          if os.path.isdir(save_to_file):
              # If save_to_file is a directory, we need to figure out the filename
              filename = None
  
              # Try to get filename from Content-Disposition header
              content_disp = response.headers.get('Content-Disposition', '')
              if 'filename=' in content_disp:
                  filename = content_disp.split('filename=')[1].strip('"\'')
  
              # If we couldn't get a filename, use the resource_id with an extension
              if not filename:
                  ext = content_type.split('/')[-1].split(';')[0]
                  if ext in ('jpeg', 'png', 'pdf', 'svg+xml'):
                      if ext == 'svg+xml':
                          ext = 'svg'
                      filename = f"{resource_id}.{ext}"
                  else:
                      filename = f"{resource_id}"
  
              save_path = os.path.join(save_to_file, filename)
          else:
              # Use the provided path directly
              save_path = save_to_file
  
          # Ensure the directory exists
          os.makedirs(os.path.dirname(os.path.abspath(save_path)), exist_ok=True)
  
          # Save the content to file
          with open(save_path, 'wb') as f:
              f.write(response.content)
  
          if self.debug:
              print(f"\nSaved resource to {save_path}")
  
          return save_path
      else:
          # Return the content
          return response.content

• penpot_mcp/server/mcp_server.py:216-216 (registration)

  The @self.mcp.tool() decorator registers the export_object function as an MCP tool named 'export_object'.

  @self.mcp.tool()