Penpot MCP Server

Instructions

        Args:
            file_id: The ID of the Penpot file to search in
            query: Search string (supports regex patterns)
        

Implementation Reference

• penpot_mcp/server/mcp_server.py:341-370 (handler)

  Main handler implementation for the 'search_object' tool. Searches object names case-insensitively using regex within the file's pagesIndex, returns matching objects with id, name, page_id, page_name, object_type.

  def search_object(file_id: str, query: str) -> dict:
      """Search for objects within a Penpot file by name.
      
      Args:
          file_id: The ID of the Penpot file to search in
          query: Search string (supports regex patterns)
      """
      try:
          file_data = get_cached_file(file_id)
          if "error" in file_data:
              return file_data
          pattern = re.compile(query, re.IGNORECASE)
          matches = []
          data = file_data.get('data', {})
          for page_id, page_data in data.get('pagesIndex', {}).items():
              page_name = page_data.get('name', 'Unnamed')
              for obj_id, obj_data in page_data.get('objects', {}).items():
                  obj_name = obj_data.get('name', '')
                  if pattern.search(obj_name):
                      matches.append({
                          'id': obj_id,
                          'name': obj_name,
                          'page_id': page_id,
                          'page_name': page_name,
                          'object_type': obj_data.get('type', 'unknown')
                      })
          return {'objects': matches}
      except Exception as e:
          return self._handle_api_error(e)
  if include_resource_tools:

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

  Helper function used by search_object to retrieve and cache file data from Penpot API.

  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/server/mcp_server.py:167-168 (registration)

  The _register_tools method where search_object is registered via @self.mcp.tool() decorator.

  """Register all MCP tools. If include_resource_tools is True, also register resource logic as tools."""
  @self.mcp.tool()