Sketch Context MCP

Note: This project is currently in testing phase and may not be fully stable.

Sketch Context MCP

A Model Context Protocol (MCP) server for integrating Sketch designs with IDEs such as Cursor, Cline, or Windsurf.

Overview

This tool allows Cursor IDE to access and interpret Sketch design files, enabling AI-powered design-to-code workflows. It works by:

1. Providing a server that parses Sketch files (.sketch)
2. Implementing the MCP protocol that Cursor or other IDEs use for context
3. Allowing you to reference specific components and layers from your Sketch files
4. Providing a UI interface for Sketch that communicates with Cursor
5. Enabling real-time bidirectional communication between Sketch and Cursor

Components

This project consists of two main components:

1. MCP Server: A Node.js server that implements the Model Context Protocol to provide Sketch file data to Cursor IDE
2. Sketch Plugin: A Sketch plugin with UI interface that communicates with the MCP server via WebSockets

Available MCP Tools

The server provides the following tools to Cursor:

• get_file: Retrieve contents of a Sketch file or specific node within it
• list_components: List all components/symbols in a Sketch file
• get_selection: Get information about currently selected elements
• create_rectangle: Create new rectangles with specified dimensions and properties
• create_text: Create new text elements with custom content and styling

These tools enable Cursor to:

• Access and inspect Sketch design files
• Query specific components and layers
• Create and modify design elements through natural language commands
• Maintain real-time synchronization with Sketch

Supported Features

• Local and Cloud Sketch file parsing
• Component/Symbol extraction
• Asset management and automatic downloads
• Selection links support via the Sketch plugin
• Real-time updates via WebSockets and SSE
• Interactive UI for connecting Sketch to Cursor
• Parsing both local and Sketch Cloud-hosted files
• Extracting document structure and component information
• Accessing specific nodes by ID
• Listing all components in a Sketch file
• Creating rectangles, text and other elements via commands from Cursor

Getting Started

Prerequisites

• Node.js (v14 or later)
• Sketch (v70 or later)
• Cursor IDE, VS Code or similar
• A Sketch account (local) or use API access (Sketch Cloud files)

Installation

Or run directly with npx:

Installing the Sketch Plugin

1. Download the latest release of the plugin from the releases page
2. Double-click the .sketchplugin file to install it in Sketch
3. The plugin will be available in Sketch under Plugins > Sketch Context MCP

Integration with Cursor

To use this with Cursor:

1. Start the MCP server with your Sketch file:
   sketch-context-mcp --local-file=/path/to/your/file.sketch
2. In Sketch, open the plugin:
   • Go to Plugins > Sketch Context MCP > Open MCP Interface
   • Enter the server port (default: 3333)
   • Click "Connect"
3. In Cursor, connect to the MCP server:
   • Go to Settings > Features > Context
   • Add a new MCP server with the URL: http://localhost:3333/sse
   • Click "Connect"
4. In the Cursor composer, you can now:
   • Reference components by ID: "Show me the component with ID 12345"
   • List all components: "List all components in the design"
   • Get details about specific elements: "Describe the button in the header"
   • Create new elements: "Create a rectangle with width 200 and height 100"

Obtaining a Sketch API Key

The Sketch API key is an OAuth access token required for accessing Sketch Cloud-hosted files. Follow these steps to obtain and use the token:

Step 1: Authenticate with Sketch Cloud

Use your Sketch Cloud credentials (email and password) to generate an access token by making a POST request to the authentication endpoint:

Replace YOUR_EMAIL and YOUR_PASSWORD with your Sketch Cloud account credentials.

Step 2: Access Token

The response will include an access_token. This token serves as your API key for accessing Sketch Cloud-hosted files.

Step 3: Using the Token

For security, it is recommended to pass the token as an environment variable:

Or include it as a command-line argument:

Step 4: Refreshing the Token

If your token expires, use the refresh_token provided in the initial response to obtain a new access token.

Security Best Practices

To ensure your API key is secure, follow these guidelines:

• Do Not Hard-Code the Key: Never hard-code an API key into the application or source code. Instead, use environment variables or secret management tools.
• Use .env Files for Local Development: Store your API key in a .env file and load it using a library like dotenv:
  SKETCH_API_KEY=<your-access-token>
  Ensure the .env file is added to .gitignore to avoid accidental exposure.
• Rotate Tokens Regularly: If your token is leaked or compromised, revoke it and generate a new one immediately.
• Monitor and Audit: Use tools to scan your repository for exposed credentials (e.g., GitHub’s secret scanning feature).
• Use Short-Lived Tokens: If possible, use short-lived tokens and refresh them as needed to minimize the impact of a leaked token.

How It Works in Sketch-Context-MCP

The Sketch API key is required for accessing Sketch Cloud-hosted files. The server uses this key to authenticate requests to Sketch Cloud and retrieve the necessary design data. The key is passed securely via the Authorization header when making API requests.

Configuration

The server can be configured using either environment variables (via .env file) or command-line arguments. Command-line arguments take precedence over environment variables.

Environment Variables

• SKETCH_API_KEY: Your Sketch API access token (required for Sketch Cloud files)
• PORT: The port to run the server on (default: 3333)
• LOCAL_SKETCH_PATH: Path to local Sketch file (alternative to --local-file argument)
• DEBUG_LEVEL: Set logging verbosity (default: 'info')

Command-line Arguments

• --version: Show version number
• --sketch-api-key: Your Sketch API access token
• --port: The port to run the server on
• --stdio: Run the server in command mode, instead of default HTTP/SSE
• --help: Show help menu

Using the Sketch Plugin

Connection Tab

The Connection tab allows you to connect to the Sketch Context MCP server:

1. Enter the port number (default is 3333)
2. Click "Connect" to establish a WebSocket connection
3. Once connected, you'll see a confirmation message with the channel ID
4. Follow the instructions for connecting Cursor to the server

Selection Tab

The Selection tab displays information about selected layers in your Sketch document:

1. Select one or more layers in your Sketch document
2. The selected layers will be displayed in the list
3. Click "Copy Selection IDs" to copy the layer IDs to your clipboard
4. Use these IDs in Cursor to reference specific layers

About Tab

The About tab provides information about the plugin and how to use it.

Using with Cursor

Once both Sketch and Cursor are connected to the MCP server:

1. Select elements in Sketch
2. Copy their IDs using the Sketch Context MCP plugin
3. In Cursor, reference these elements by their IDs

Example commands in Cursor:

• "Show me the details of the layer with ID 12345"
• "Create a blue rectangle with width 300 and height 200"
• "Add a text layer with the content 'Hello World'"

Troubleshooting

Common Issues

• Connection Errors: Make sure your server is running and the port is accessible
• Authentication Failures: Verify your Sketch API key is correct
• File Parsing Issues: Ensure your Sketch file is valid and not corrupted
• WebSocket Connection Failed: Ensure the port is not blocked by a firewall

Logs

To enable detailed logging, set the DEBUG environment variable:

Contributing

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

License

This project is licensed under the MIT License - see the LICENSE file for details.