A Kotlin-based desktop companion for seamless Figma-to-MCP integration
Ported from the original TypeScript project with enhanced desktop capabilities

Installation • Getting Started • Features • Original Project • Troubleshooting

• 🚀 Start/Stop Servers: Control WebSocket and MCP servers from tray menu
• 📊 View Logs: Built-in log viewer with clear and copy functions
• ⚙️ MCP Configuration: Easy copy-paste configuration for Cursor or whatever
• 🔄 Auto Port Management: Automatic port conflict resolution
• 🖥️ System Tray: Clean interface with status indicators
• 📈 Analytics & Crash Reporting: Google Analytics integration for monitoring app usage and crashes

1. Go to Releases
2. Download the appropriate version for your platform:
   • macOS Apple Silicon: TalkToFigma-v*.*.* -arm64.dmg
   • macOS Intel: TalkToFigma-v*.*.* -intel.dmg
   • Windows: TalkToFigma-v*.*.*.msi or .exe

Since this is an open source community build (unsigned), your system will show security warnings:

macOS:

1. "Cannot be opened" dialog will appear
2. Go to System Preferences → Security & Privacy → General
3. Click "Open Anyway" next to the blocked app message
4. Or right-click the app → "Open" → "Open" in the confirmation dialog

Windows:

1. SmartScreen warning: "Windows protected your PC"
2. Click "More info" → "Run anyway"
3. This is normal for applications not yet recognized by Microsoft's reputation system

• macOS: Find in Applications folder or Launchpad
• Windows: Start menu → Cursor Talk to Figma desktop

The application will appear in your system tray with a server icon.

Right-click the system tray icon and select:

• "Start All Services" - Starts both WebSocket (port 3055) and MCP (port 3056) servers
• Or start them individually if needed

You'll see status indicators:

• : Servers running
• : Servers stopped

1. Click the tray icon → "MCP Configuration"
2. Copy the displayed configuration
3. Paste into your Cursor settings under MCP servers:

{
  "mcpServers": {
    "Figma": {
      "url": "http://127.0.0.1:3845/mcp"
    },
    "TalkToFigmaDesktop": {
      "url": "http://127.0.0.1:3056/sse"
    }
  }
}

Install the official plugin: Cursor Talk to Figma MCP Plugin

1. In Figma: Run the plugin and ensure it connects to the desktop app
2. In Cursor: The MCP server will now be available for AI interactions
3. Start Creating: Use Cursor AI with seamless Figma integration!

🔌 Connection Problems

1. Right-click the tray icon → "Kill All Servers"
2. Wait a few seconds, then → "Start All Services"
3. If still not working → "View Logs" to see what's happening

🛡️ Installation & Security Issues

• macOS: If "Cannot be opened" appears → System Preferences → Security & Privacy → "Open Anyway"
• Windows: If SmartScreen warning appears → "More info" → "Run anyway"
• Why warnings occur: Community builds are unsigned (no code signing certificate) but are safe to use

🔧 Server Won't Start

1. Right-click tray icon → "Kill All Servers"
2. Try → "Start All Services" again
3. Still having issues? → "View Logs" for details

Access detailed logs via:

1. Right-click tray icon → "View Logs"
2. Use Clear to reset log view to current session
3. Use Copy to share logs for troubleshooting

• JDK 21+
• Kotlin 2.0.0+
• Gradle 8.12+
• direnv (for environment variable management)

1. Install direnv

   # macOS
   brew install direnv
   
   # Setup shell integration (add to your shell config)
   echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc  # for zsh
   echo 'eval "$(direnv hook bash)"' >> ~/.bashrc  # for bash

2. Create environment file

   cp .envrc.template .envrc

3. Configure Java environment

   The .envrc file automatically sets up the correct Java version:

   # Java Development Kit
   # Amazon Corretto JDK 21 setup with automatic detection
   if [ -d "/Library/Java/JavaVirtualMachines/amazon-corretto-21.jdk/Contents/Home" ]; then
       export JAVA_HOME="/Library/Java/JavaVirtualMachines/amazon-corretto-21.jdk/Contents/Home"
       export PATH="$JAVA_HOME/bin:$PATH"
       echo "✅ Amazon Corretto JDK 21 loaded"
   fi
   
   # Optional: Google Analytics (uncomment to enable)
   # export GOOGLE_ANALYTICS_ID="G-XXXXXXXXXX"
   # export GOOGLE_ANALYTICS_API_SECRET="your_api_secret_here"

   [!NOTE] Java Version: This project requires JDK 21. The .envrc file automatically detects Amazon Corretto JDK 21 and sets up the environment. If you don't have JDK 21 installed, install it with: brew install --cask amazon-corretto

4. Allow direnv

   direnv allow

# Clone the repository
git clone https://github.com/FigmaAI/TalkToFigmaDesktop.git
cd TalkToFigmaDesktop

# Build the application
./gradlew build

# Run during development
./gradlew :app:run

# Create unsigned distributables
./gradlew packageDmg -PsigningEnabled=false        # macOS (ARM64 by default)
./gradlew packageMsi packageExe                     # Windows

# Create Intel macOS build
./gradlew packageDmg -PsigningEnabled=false -Dcompose.desktop.mac.archs=x86_64

cursor-talk-to-figma-mcp by @sonnylazuardi

Both implementations share the same core MCP protocol and Figma plugin compatibility.

We welcome contributions! Please see our Contributing Guidelines for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

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

• 🐛 Report Issues
• 💡 Request Features
• 💬 Discussions

This application is built using various open source libraries. The key dependencies are:

• Kotlin & Jetpack Compose: Modern UI toolkit (Apache 2.0)
• MCP Kotlin SDK: Model Context Protocol implementation (MIT)
• OkHttp: HTTP client library (Apache 2.0)
• Jackson: JSON processing (Apache 2.0)
• Logback: Logging framework (EPL 1.0, LGPL 2.1)

_{Built with ❤️ using Kotlin and Compose for Desktop}