Sketch MCP Server

English | 中文

A Sketch file processing server based on Model Context Protocol (MCP), designed for AI tools to intelligently analyze Sketch design files and generate code.

✨ Core Features

• 🎨 Sketch File Analysis: Comprehensive parsing of Sketch files, extracting nodes, styles, hierarchies, and complete information
• 🚀 Smart Token Optimization: Up to 90% token consumption reduction, significantly lowering AI call costs
• 🔍 Intelligent Query System: 16 professional tools for efficient discovery and analysis of design elements
• 🎯 Symbol Component Support: Complete Symbol Master and Instance processing capabilities
• 🖼️ Visual Rendering: Render design nodes as SVG/PNG images for AI analysis
• 📊 Detailed Statistical Analysis: Comprehensive statistics for documents and nodes
• 🔧 CLI Tool Support: Support for direct npx calls without installation

📦 Installation

Global Installation (Recommended)

npm install -g sketch-mcp-server

Using npx (No Installation Required)

npx sketch-mcp-server

Local Project Installation

npm install sketch-mcp-server

🚀 Quick Start

Command Line Launch

# Start MCP server (stdio mode)
sketch-mcp-server

# Or use npx
npx sketch-mcp-server

AI Tool Integration

This server is designed for the following AI development environments:

• Trae AI: As an MCP server for Sketch file analysis
• Cursor: Configure as MCP tool for design-to-code workflow
• Claude Desktop: For Sketch file processing and analysis

Trae AI Configuration Example

Add MCP server configuration in Trae AI:

{
  "mcpServers": {
    "sketch-mcp-server": {
      "command": "npx",
      "args": ["sketch-mcp-server"]
    }
  }
}

🛠️ Tool List

📁 File Loading Tools

Tool Name	Description
loadSketchByPath	Load Sketch file from file system
loadSketchByConfig	Load Sketch data from configuration object

📊 Document Structure Tools

Tool Name	Description	Optimization Features
getDocumentStructure	Get complete document hierarchy	🚀 Supports field filtering and summary mode
getPageStructure	Get single page structure	-
listPages	List all page basic information	-

🎯 Node Query Tools

Tool Name	Description	Token Optimization
getNodesSummary	Smart Node Summary	🔥 80-90% Token Reduction
listNodes	List nodes (with filtering support)	-
listNodesByPage	List nodes by page	-
findNodesByName	Search nodes by name	-

🔍 Detailed Information Tools

Tool Name	Description
getNodeInfo	Get detailed information for single node
getMultipleNodeInfo	Batch get node information (up to 100)
getNodePosition	Get node position information

🔄 Symbol Component Tools

Tool Name	Description
getSymbolMasters	Get all Symbol Masters
getSymbolInstances	Get all Symbol Instances
getSymbolMasterBySymbolID	Find Master by Symbol ID
getSymbolInstanceStyles	Get instance styles (including override styles)

🎨 Visualization Tools

Tool Name	Description
renderNodeAsBase64	Render node as image (SVG/PNG)

💡 Token Optimization Strategy

Data Volume Comparison

Tool/Mode	Token Reduction	Use Case
getNodesSummary	80-90%	Initial analysis, understanding overall structure
getDocumentStructure (summary mode)	70-85%	Quick document structure overview
getDocumentStructure (field filtering)	30-50%	Structural analysis
Full mode	0%	Detailed design requirements

Recommended Workflow

1. 🔍 Quick Analysis: Use getNodesSummary to understand overall design structure
2. 📋 Structure Analysis: Use field-filtered getDocumentStructure to get hierarchical relationships
3. 🎯 Detailed Information: Get detailed information for specific nodes as needed
4. 👁️ Visual Verification: Render key components to confirm effects

📝 Usage Examples

Basic Workflow

// 1. Load Sketch file
{
  "name": "loadSketchByPath",
  "arguments": {
    "path": "/path/to/design.sketch"
  }
}

// 2. Get smart summary (save 80-90% tokens)
{
  "name": "getNodesSummary",
  "arguments": {
    "groupBy": "type",
    "includeStats": true,
    "maxSamples": 5
  }
}

// 3. Get detailed information for specific nodes
{
  "name": "getMultipleNodeInfo",
  "arguments": {
    "nodeIds": ["button-id", "text-id"]
  }
}

// 4. Render node as image
{
  "name": "renderNodeAsBase64",
  "arguments": {
    "nodeId": "button-id",
    "format": "svg"
  }
}

Advanced Optimization Examples

// Use field filtering to reduce data volume
{
  "name": "getDocumentStructure",
  "arguments": {
    "fields": ["id", "name", "type", "children"],
    "maxDepth": 3,
    "summaryMode": false
  }
}

// Smart summary grouped by style
{
  "name": "getNodesSummary",
  "arguments": {
    "groupBy": "style",
    "includeStats": true,
    "maxSamples": 3
  }
}

🎯 Tool Selection Guide

Use Case	Recommended Tool	Token Efficiency	Description
Understanding overall structure	getNodesSummary	⭐⭐⭐⭐⭐	Most efficient overview method
Analyzing page hierarchy	getDocumentStructure (filtered)	⭐⭐⭐⭐	Structured hierarchical information
Finding specific nodes	findNodesByName	⭐⭐⭐	Precise search
Getting detailed information	getMultipleNodeInfo	⭐⭐	Batch retrieval
Handling Symbol components	getSymbolMasters	⭐⭐⭐	Component-based design
Visual confirmation	renderNodeAsBase64	⭐⭐	Intuitive effect viewing

🔧 Development Guide

Environment Requirements

• Node.js >= 16.0.0
• npm or yarn

Local Development

# Clone project
git clone https://github.com/mater1996/sketch-mcp-server.git
cd sketch-mcp-server

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Start development server
npm run start:mcp

Available Scripts

npm run build          # Build TypeScript to JavaScript
npm run test           # Run test suite
npm run test:coverage  # Run tests and generate coverage report
npm run start          # Start HTTP server
npm run start:mcp      # Start MCP stdio server
npm run release        # Release new version
npm run release:dry    # Simulate release process

📚 API Reference

For detailed API documentation, please refer to Tool Usage Guide.

Development Standards

• Write code in TypeScript
• Follow existing code style
• Add tests for new features
• Update relevant documentation

📄 License

MIT License

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

If you encounter any issues or have questions, please:

1. Check the documentation
2. Search existing issues
3. Create a new issue if needed