F-MCP (Figma MCP Bridge)

Figma tasarım verilerini ve işlemlerini Model Context Protocol (MCP) ile AI asistanlarına (Claude, Cursor vb.) açan MCP sunucusu ve Figma plugin'i. Bu repo MCP sunucusu ve F-MCP Bridge Figma plugin kaynağını içerir.

Figma API token tüketmiyor

figma-mcp-bridge, Figma'nın REST API'sini kullanmıyor. Akış:

Claude (MCP) → figma-mcp-bridge → Plugin → Figma (Desktop veya Tarayıcı)

Sorgular doğrudan Figma içinde çalışan plugin üzerinden gider — hem masaüstü uygulaması hem tarayıcı sürümü (figma.com) desteklenir. Bu sayede:

• Figma API token tüketimi yok (REST API hiç çağrılmıyor)
• Rate limit yok
• Figma tarafında ücretlendirme yok
• Desktop'ta internet bağlantısı gerekmez; tarayıcı Figma'da yalnızca figma.com erişimi yeterli

Ne tüketiliyor? Sadece AI tarafı: bu konuşmadaki context token'ları. Her tool call'ın request/response'u context penceresine girer. Büyük dosyalarda çok derin sorgular (örn. depth: 3, verbosity: full) Claude context'ini hızlı doldurabilir; Figma tarafında ek maliyet oluşmaz.

Zero Trust

Veri yalnızca sizin ortamınızda kalır. Tasarım içeriği Figma bulutuna MCP üzerinden gönderilmez; akış Claude → MCP (yerel) → Plugin (yerel) → Figma (Desktop veya Tarayıcı).

REST API çağrısı ve Figma'ya tasarım verisi aktarımı yoktur. Bu sayede kurumsal güvenlik ve gizlilik politikalarına uyum kolaylaşır (Zero Trust: sunucuya güvenme, yerelde doğrula).

Kurumlar için özet

• Debug modu kapalı. Figma'yı normal açarsınız; ekstra debug portu veya geliştirici ayarı gerekmez.
• Kendi plugin story'nizde yayınlama. Plugin'i Figma Organization (veya Enterprise) altında kendi plugin story'nize yayınladığınızda tüm kullanıcılar Plugins menüsünden tek tıkla erişir; "manifest import" zorunluluğu kalkar, merkezi ve erişilebilir bir mimari olur.
• KVKK / GDPR uyumu. Tasarım verisi yalnızca kullanıcının makinesinde (MCP + Plugin + Figma Desktop) kalır; Figma bulutuna veya üçüncü tarafa MCP üzerinden gönderilmez. Veri minimizasyonu ve yerelde işleme, hassas kurumsal ekipler ve denetim gereksinimleri için uygun bir model sunar.

F-MCP yetenekleri

33 araç (config'te dist/local-plugin-only.js kullanıldığında tamamı aktif). Tam liste: TOOLS_FULL_LIST.md. Aşağıda rollerine göre özet.

Ürün yöneticileri (analiz, kabul kriterleri, kurumsal süreçler)

| Kullanım | Araçlar | Açıklama | | --------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | Tasarım envanteri ve analiz | figma_get_design_system_summary, figma_get_file_data | Özet, bileşen sayıları, token koleksiyonları; büyük dosyada varsayılan currentPageOnly (timeout önlemi) | | Kabul kriterleri ve dokümantasyon | figma_get_component_for_development, figma_capture_screenshot | Bileşen spec + görsel; test ve kabul için referans | | Design–code uyumu (gap analizi) | figma_check_design_parity | Figma token'ları ile kod token'larını karşılaştırır; kurumsal raporlama ve test kriterleri | | Keşif ve durum | figma_search_components, figma_get_status | Bileşen arama (varsayılan currentPageOnly), bağlantı kontrolü |

Geliştiriciler

| Kullanım | Araçlar | Açıklama | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | Bileşen ve implementasyon | figma_get_component, figma_get_component_for_development, figma_get_component_image, figma_instantiate_component, figma_set_instance_properties | Metadata, screenshot, instance oluşturma ve property güncelleme | | Token ve stil kodu | figma_get_variables, figma_get_styles | Değişkenler ve stiller (CSS/Tailwind/TS export) | | Dosya yapısı / design context | figma_get_file_data, figma_get_design_context | Yapı, metin, layout, renk, font; SUI bileşen/token adı, layoutSummary, colorHex, fillVariableNames; outputHint: react/tailwind | | Çalıştırma ve doğrulama | figma_execute, figma_capture_screenshot, figma_get_console_logs, figma_watch_console, figma_clear_console | Plugin API'de JS, screenshot, console log okuma/izleme/temizleme |

DesignOps ve tasarımcılar

| Kullanım | Araçlar | Açıklama | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | DesignOps (kritik) | figma_check_design_parity, figma_setup_design_tokens, figma_batch_create_variables, figma_batch_update_variables | Design–code gap, koleksiyon+modlar+variable (rollback), toplu token yönetimi | | Değişken ve stil yönetimi | figma_get_variables, figma_get_styles, figma_create_variable_collection, figma_create_variable, figma_update_variable, figma_delete_variable, figma_rename_variable, figma_add_mode, figma_rename_mode, figma_refresh_variables, figma_get_token_browser | Tüm variable/stil CRUD ve Token Browser | | Bileşen kütüphanesi | figma_get_design_system_summary, figma_search_components, figma_arrange_component_set, figma_set_description | Özet/arama (currentPageOnly varsayılan; SUI/büyük dosyada timeout önlemi), variant set, dokümantasyon |

Kurulum: En basit (repo indirmeden): aşağıdaki En basit kurulum adımları. Detaylı: Kurulum rehberi (Onboarding). Windows: WINDOWS-INSTALLATION.md (Node veya Python bridge).

Hızlı başlangıç

Plugin'in "ready (:5454)" olması için önce MCP bridge sunucusu çalışıyor olmalı; sonra Figma'da plugin'i açarsınız.

⚠️ Önemli: Cursor veya Claude Desktop kullanıyorsanız npm run dev:local çalıştırMAYIN. MCP sunucusu bu uygulamalar tarafından otomatik başlatılır. İki sunucu aynı anda çalışırsa port çatışması oluşur ve plugin yanlış sunucuya bağlanabilir.

En basit kurulum (NPX — repo indirmeden)

Repo klonlamadan, sadece Node.js ve tek bir config ile kurulum. Güncellemek için paket otomatik güncellenir (@latest).

| Adım | Yapılacak | | ---- | ------------------------------------------------------------------------------------------------------------ | | 1 | Node.js kur — nodejs.org LTS. Terminalde node -v ile kontrol edin. | | 2 | MCP config ekle — Aşağıdaki JSON bloğunu Cursor veya Claude config dosyasına ekleyin. | | 3 | Cursor veya Claude'u yeniden başlatın — MCP sunucusu port 5454'te otomatik başlar. | | 4 | Figma'da plugini açın — Plugins → F-MCP ATezer Bridge → "ready (:5454)" görünene kadar bekleyin. |

Cursor — Proje kökünde veya kullanıcı dizininde .cursor/mcp.json:

{
  "mcpServers": {
    "figma-mcp-bridge": {
      "command": "npx",
      "args": ["-y", "@atezer/figma-mcp-bridge@latest"]
    }
  }
}

Claude Desktop — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json | Windows: %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "figma-mcp-bridge": {
      "command": "npx",
      "args": ["-y", "@atezer/figma-mcp-bridge@latest"]
    }
  }
}

İlk çalıştırmada npx paketi indirir; sonraki açılışlarda cache'den çalışır. Plugin'i Figma'da ilk kez kullanıyorsanız Plugin'i Figma'ya yükleyin adımına bakın.

A) Clone + build ile (Cursor / Claude)

Repo'yu indirip kendi makinenizde build etmek isterseniz (ör. ağ erişimi kısıtlı ortam):

1. Build (bir kez):

cd <proje-yolu>
npm install
npm run build:local

2. MCP config — command: "node", args: ["<PROJE-YOLU>/dist/local-plugin-only.js"] (tam yolu yazın).

Cursor — .cursor/mcp.json | Claude — claude_desktop_config.json (yolu yukarıdaki gibi).

3. Cursor/Claude'u yeniden başlatın.
4. Figma'da plugini çalıştırın → "ready (:5454)" bekleyin.

Permission denied? "command": "bash", "args": ["-c", "cd <PROJE-YOLU> && exec node dist/local-plugin-only.js"] kullanın.

B) Manuel geliştirme / debug

Bu yöntem sadece bridge/plugin geliştirmesi veya debug içindir. Cursor/Claude Desktop ile aynı anda kullanmayın.

cd <proje-yolu>
npm install
npm run dev:local

Çıktıda Plugin bridge server listening geçen satırı görünce Figma'da plugin'i açın.

Port çatışması: Aynı porta iki F-MCP bridge bağlanamaz. Port meşgulse sunucu açık hata mesajı verir ve durur (sessiz port değiştirme yoktur). lsof -i :5454 (macOS/Linux) veya netstat -ano | findstr :5454 (Windows) ile mevcut process'i bulun ve kapatın.

Plugin'i Figma'ya yükleyin (ilk seferde)

1. Figma'yı açın.
2. Plugins → Development → Import plugin from manifest…
3. Bu repodaki f-mcp-plugin/manifest.json dosyasını seçin.
4. Plugin listede "F-MCP ATezer Bridge" olarak görünür.

Plugin durum göstergeleri

| Durum | Anlam | | --------------- | ----------------------------------------------------------------------- | | connecting... | WebSocket açıldı, sunucudan handshake bekleniyor | | ready (:5454) | F-MCP bridge'e başarıyla bağlandı (port numarası gösterilir) | | wrong server | Bağlantı kuruldu ama karşıdaki F-MCP bridge değil (eski/yanlış process) | | no server | Sunucu kapalı veya erişilemiyor |

Claude / Cursor ile bağlama (detay)

NPX: Paket npm'de @atezer/figma-mcp-bridge adıyla yayınlı. npx @atezer/figma-mcp-bridge@latest ile clone yapmadan kullanılabilir. Bkz. NPX-INSTALLATION.md.

Tam mod (console/screenshot): Config'te dist/local-plugin-only.js yerine dist/local.js kullanın; Figma'yı --remote-debugging-port=9222 ile açın.

Çoklu kullanıcı (multi-instance): Aynı anda birden fazla kişi kullanacaksa her kullanıcı farklı port (5454, 5455, … 5470) seçer; MCP config'e "env": { "FIGMA_PLUGIN_BRIDGE_PORT": "5455" } ekleyin, plugin'de aynı portu girin. Detay: MULTI_INSTANCE.md.

Enterprise: Audit log (FIGMA_MCP_AUDIT_LOG_PATH), air-gap kurulum ve Organization plugin: ENTERPRISE.md.

"Server disconnected" / "wrong server"? (1) Port 5454'te başka bir process var mı kontrol edin: lsof -i :5454. (2) Cursor/Claude Desktop kullanıyorsanız npm run dev:local çalışmıyor olmalı. (3) Build güncel mi: npm run build:local.

Browser Figma desteği

Plugin, Figma'nın tarayıcı sürümünde de (figma.com) çalışır. Desktop uygulaması zorunlu değildir.

Aynı makinede (tarayıcı + MCP bridge aynı bilgisayarda):

1. MCP bridge sunucusunu başlatın (Cursor/Claude Desktop açın veya npm run dev:local).
2. Figma'yı tarayıcıda açın → Plugin'i çalıştırın.
3. Plugin UI'da Host: localhost, Port: 5454 → "ready (:5454)" göründüğünde hazır.

Uzak makinede (tarayıcı bir bilgisayarda, MCP bridge başka bir makinede):

1. MCP bridge makinesinde FIGMA_BRIDGE_HOST=0.0.0.0 env var ile sunucuyu başlatın (tüm ağ arayüzlerinden erişim açılır).
2. Plugin UI'da Host alanına MCP bridge makinesinin IP adresini girin (örn. 192.168.1.50), Port: 5454.
3. Manifest güncellemesi gerekir: Uzak IP'yi manifest.json dosyasındaki networkAccess.allowedDomains dizisine ekleyin (örn. "ws://192.168.1.50:5454"). Organization plugin olarak dağıtıldığında admin bunu yapılandırır.
4. Firewall'da port 5454'ün açık olduğundan emin olun.

Güvenlik: Default olarak sunucu yalnızca 127.0.0.1'de dinler (Zero Trust). Uzak erişim için FIGMA_BRIDGE_HOST=0.0.0.0 bilinçli olarak ayarlanmalı ve firewall ile korunmalıdır.

Design / Dev Mode / FigJam

Design seat olmayan, sadece Dev Mode erişimi olan kullanıcılar da bu MCP'yi kullanabilir. Plugin Design, Dev Mode ve FigJam dahil tüm editör tiplerinde çalışır (editorType: ["figma", "figjam", "dev"]). MCP bağlantısı için mod farkı engel değildir.

• Dev Mode kullanıcıları (SEM, PO, Dev): Dosyayı Dev Mode'da açın → sağ panelde Plugins sekmesi → F-MCP ATezer Bridge ile çalıştırın.
• FigJam kullanıcıları: FigJam dosyasını açın → Plugins → F-MCP ATezer Bridge ile çalıştırın. FigJam'de brainstorm, flow ve diyagram verilerine MCP üzerinden erişebilirsiniz.

Detay: ONBOARDING.md (Dev Mode bölümü).

Plugin–MCP bağlantı özeti: İki mod var; debug portu zorunlu değil. Plugin-only (önerilen): Config'te dist/local-plugin-only.js, Figma normal açılır, token yok. Tam mod: Config'te dist/local.js, Figma --remote-debugging-port=9222 ile açılır (console/screenshot için). Ayrıntı: PLUGIN-MCP-BAGLANTI.md.

Detaylı Rehber

Plugin'in MCP ile nasıl konuştuğu, veri akışı, Design/Dev mode ve sorun giderme için:

• Windows kurulum rehberi — Windows 10/11, Node veya Python bridge, Claude config, port, sorun giderme
• Plugin–MCP Bağlantı Rehberi (mimari, kurulum, sözleşmeler)
• Plugin Nasıl Çalışır? (Worker/UI akışı, WebSocket vs CDP)

Repo İçeriği

• f-mcp-plugin/ – F-MCP ATezer Bridge plugin kaynağı (manifest, code.js, ui.html)
• docs/ – Kurulum, mod karşılaştırma, Plugin nasıl çalışır, sorun giderme
• src/ – MCP sunucusu (local, plugin-only, Cloudflare Worker)
• python-bridge/ – Python MCP bridge (Node.js kurulumu olmayan ortamlar için); aynı WebSocket protokolü, port 5454

Tüm dokümanlar (docs/)

| Dosya | Açıklama | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | ONBOARDING.md | Kurulum rehberi (Onboarding) — Plugin yükle, Node.js, MCP başlat, Claude config | | WINDOWS-INSTALLATION.md | Windows kurulum — Node veya Python bridge, Claude config (Windows yolu), port, sorun giderme | | SETUP.md | Kurulum (Remote / Local) | | PLUGIN-MCP-BAGLANTI.md | Plugin–MCP mimari ve kurulum | | PLUGIN-NASIL-CALISIR.md | Plugin Worker/UI akışı | | MODE_COMPARISON.md | Mod karşılaştırma | | TOOLS.md | MCP araçları referansı | | TOOLS_FULL_LIST.md | 33 araç tam liste (referans, Claude ile doğrulanmış) | | DEVELOPER_FIGMA_CAPABILITIES.md | Cursor + F-MCP: Neyi alır/almaz, birebir çıkartma, code-ready/SUI/token referansı, ileride | | TROUBLESHOOTING.md | Sorun giderme | | NPX-INSTALLATION.md | NPX ile kurulum | | OAUTH_SETUP.md | OAuth (remote sunucu) | | SELF_HOSTING.md | Kendi sunucunda host | | DEPLOYMENT_COMPARISON.md | Dağıtım karşılaştırma | | ARCHITECTURE.md | Teknik mimari | | USE_CASES.md | Örnek kullanım senaryoları | | RECONSTRUCTION_FORMAT.md | Reconstruction format | | BITBUCKET-README.md | Bitbucket README şablonu | | PORT-5454-KAPALI.md | Port 5454 kapalı sorun giderme | | MULTI_INSTANCE.md | Çoklu kullanıcı — Aynı anda birden fazla kişi (port 5454–5470) | | ENTERPRISE.md | Enterprise — Audit log, air-gap, Organization plugin | | PUBLISH-PLUGIN.md | Publish plugin — Figma'da yayınlama: Data security cevapları, final details, Plugin ID | | | |

Yaygınlaştırma: Organization (private) plugin

Çalışma biçimini ekip/organizasyon içinde kolaylaştırmak için Figma Organization private plugin olarak yayınlamak mantıklı bir ilk adım. Enterprise odaklı özellikler (audit log, air-gap, org plugin detayı): ENTERPRISE.md.

Avantajlar:

• Herkesin "Import plugin from manifest" yapması gerekmez; plugin organizasyonun plugin listesinde görünür.
• Sadece Plugins menüsünden (veya Resources → Plugins) ekleyip çalıştırırlar; MCP bridge'i (Claude config) kendi makinede kurmaları yeterli.
• Review süreci yok (private plugin); yayınladıktan kısa süre sonra kullanılabilir.

Gereksinimler:

• Figma Organization veya Enterprise planı (Figma: Create private organization plugins).
• Yayınlama: Publish plugins adımlarını izleyin; Publish to kısmında organization'ı seçin (Community değil).

Özet: Önce organization private plugin yapmak, "plugin'i herkese tek tıkla ulaştırma" adımını çözer; MCP tarafında (Claude config, build, port) kurulum aynı kalır. Sonrasında isteğe bağlı olarak Community'e açmak veya self-host MCP ile tam entegrasyon düşünülebilir.

Lisans ve Destek

• Lisans: MIT tabanlı, ek kısıt: ticari amaçlı kullanılmaz; sadece kişisel kullanım içindir (bkz. LICENSE)
• Sorun bildirimi: GitHub Issues