Penpot MCP Server

Instructions

Implementation Reference

• penpot_mcp/server/mcp_server.py:270-339 (handler)

  The primary handler for the 'get_object_tree' MCP tool. Retrieves cached file data, extracts subtree using helper function, generates rendered image with URI, handles JSON/YAML formatting, and manages errors.
  @self.mcp.tool() def get_object_tree( file_id: str, object_id: str, fields: List[str], depth: int = -1, format: str = "json" ) -> dict: """Get the object tree structure for a Penpot object ("tree" field) with rendered screenshot image of the object ("image.mcp_uri" field). Args: file_id: The ID of the Penpot file object_id: The ID of the object to retrieve fields: Specific fields to include in the tree (call "penpot_tree_schema" resource/tool for available fields) depth: How deep to traverse the object tree (-1 for full depth) format: Output format ('json' or 'yaml') """ try: file_data = get_cached_file(file_id) if "error" in file_data: return file_data result = get_object_subtree_with_fields( file_data, object_id, include_fields=fields, depth=depth ) if "error" in result: return result simplified_tree = result["tree"] page_id = result["page_id"] final_result = {"tree": simplified_tree} try: image = export_object( file_id=file_id, page_id=page_id, object_id=object_id ) image_id = hashlib.md5(f"{file_id}:{object_id}".encode()).hexdigest() self.rendered_components[image_id] = image # Image URI preferences: # 1. HTTP server URL if available # 2. Fallback to MCP resource URI image_uri = f"render_component://{image_id}" if hasattr(image, 'http_url'): final_result["image"] = { "uri": image.http_url, "mcp_uri": image_uri, "format": image.format if hasattr(image, 'format') else "png" } else: final_result["image"] = { "uri": image_uri, "format": image.format if hasattr(image, 'format') else "png" } except Exception as e: final_result["image_error"] = str(e) if format.lower() == "yaml": try: import yaml yaml_result = yaml.dump(final_result, default_flow_style=False, sort_keys=False) return {"yaml_result": yaml_result} except ImportError: return {"format_error": "YAML format requested but PyYAML package is not installed"} except Exception as e: return {"format_error": f"Error formatting as YAML: {str(e)}"} return final_result except Exception as e: return self._handle_api_error(e)
• penpot_mcp/tools/penpot_tree.py:389-494 (helper)

  Key helper function called by the handler to construct the filtered object subtree, respecting field selection, depth limits, circular reference detection, and recursive child traversal.
  def get_object_subtree_with_fields(file_data: Dict[str, Any], object_id: str, include_fields: Optional[List[str]] = None, depth: int = -1) -> Dict[str, Any]: """ Get a filtered tree representation of an object with only specified fields. This function finds an object in the Penpot file data and returns a subtree with the object as the root, including only the specified fields and limiting the depth of the tree if requested. Args: file_data: The Penpot file data object_id: The ID of the object to get the tree for include_fields: List of field names to include in the output (None means include all) depth: Maximum depth of the tree (-1 means no limit) Returns: Dictionary containing the filtered tree or an error message """ try: # Get the content from file data content = file_data.get('data', file_data) # Find which page contains the object page_id = find_page_containing_object(content, object_id) if not page_id: return {"error": f"Object {object_id} not found in file"} # Get the page data page_data = content.get('pagesIndex', {}).get(page_id, {}) objects_dict = page_data.get('objects', {}) # Check if the object exists in this page if object_id not in objects_dict: return {"error": f"Object {object_id} not found in page {page_id}"} # Track visited nodes to prevent infinite loops visited = set() # Function to recursively build the filtered object tree def build_filtered_object_tree(obj_id: str, current_depth: int = 0): if obj_id not in objects_dict: return None # Check for circular reference if obj_id in visited: # Return a placeholder to indicate circular reference return { 'id': obj_id, 'name': objects_dict[obj_id].get('name', 'Unnamed'), 'type': objects_dict[obj_id].get('type', 'unknown'), '_circular_reference': True } # Mark this object as visited visited.add(obj_id) obj_data = objects_dict[obj_id] # Create a new dict with only the requested fields or all fields if None if include_fields is None: filtered_obj = obj_data.copy() else: filtered_obj = {field: obj_data[field] for field in include_fields if field in obj_data} # Always include the id field filtered_obj['id'] = obj_id # If depth limit reached, don't process children if depth != -1 and current_depth >= depth: # Remove from visited before returning visited.remove(obj_id) return filtered_obj # Find all children of this object children = [] for child_id, child_data in objects_dict.items(): if child_data.get('parentId') == obj_id: child_tree = build_filtered_object_tree(child_id, current_depth + 1) if child_tree: children.append(child_tree) # Add children field only if we have children if children: filtered_obj['children'] = children # Remove from visited after processing visited.remove(obj_id) return filtered_obj # Build the filtered tree starting from the requested object object_tree = build_filtered_object_tree(object_id) if not object_tree: return {"error": f"Failed to build object tree for {object_id}"} return { "tree": object_tree, "page_id": page_id } except Exception as e: return {"error": str(e)}
• penpot_mcp/server/mcp_server.py:146-154 (schema)

  MCP resource that serves the JSON schema defining available fields in Penpot object trees, referenced in the get_object_tree tool documentation.
  @self.mcp.resource("penpot://tree-schema", mime_type="application/schema+json") def penpot_tree_schema() -> dict: """Provide the Penpot object tree schema as JSON.""" schema_path = os.path.join(config.RESOURCES_PATH, 'penpot-tree-schema.json') try: with open(schema_path, 'r') as f: return json.load(f) except Exception as e: return {"error": f"Failed to load tree schema: {str(e)}"}
• penpot_mcp/server/mcp_server.py:270-271 (registration)

  Decorator that registers the get_object_tree function as an MCP tool.
  @self.mcp.tool() def get_object_tree(