remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Integrations
Provides integration with Figma's API for read-only access to Figma files and projects, with architecture supporting design token and theme management features
Figma MCP 서버
Claude 및 기타 MCP 호환 클라이언트를 통해 Figma API와의 통합을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 현재 Figma 파일 및 프로젝트에 대한 읽기 전용 액세스를 지원하며, 서버 측 아키텍처는 더욱 고급 디자인 토큰 및 테마 관리 기능을 지원할 수 있습니다(Figma API 개선 또는 플러그인 개발 예정).
프로젝트 상태
현재 진행 상황
- ✅ 핵심 구현 : Model Context Protocol(MCP)에 따라 TypeScript 서버를 성공적으로 구축했습니다.
- ✅ Claude Desktop 통합 : Claude Desktop에서 테스트 및 작동됨
- ✅ 읽기 작업 : Figma 파일 액세스를 위한
get-file및list-files도구 사용 - ✅ 서버 아키텍처 : 캐싱 시스템, 오류 처리 및 통계 모니터링 구현
- ✅ 전송 프로토콜 : stdio 및 SSE 전송 메커니즘 모두 지원됨
잠재적인 전체 기능
이 서버는 다음 기능을 지원하는 코드로 설계되었습니다(현재 API 제한으로 제한됨).
- 변수 관리 : 디자인 토큰(변수)을 생성, 읽기, 업데이트 및 삭제합니다.
- 참조 처리 : 토큰 간 관계 생성 및 검증
- 테마 관리 : 다양한 모드(예: 밝음/어둠)로 테마를 만듭니다.
- 종속성 분석 : 순환 참조 감지 및 방지
- 일괄 작업 : 변수 및 테마에 대한 대량 작업 수행
Figma 플러그인 개발이나 확장된 API 액세스를 통해 이러한 기능을 완벽하게 구현할 수 있습니다.
특징
- 🔑 Figma API를 통한 안전한 인증
- 📁 파일 작업(읽기, 나열)
- 🎨 디자인 시스템 관리
- 변수 생성 및 관리
- 테마 생성 및 구성
- 참조 처리 및 검증
- 🚀 성능 최적화
- LRU 캐싱
- 속도 제한 처리
- 연결 풀링
- 📊 종합 모니터링
- 건강 검진
- 사용 통계
- 오류 추적
필수 조건
- Node.js 18.x 이상
- 적절한 권한이 있는 Figma 액세스 토큰
- MCP(Model Context Protocol)에 대한 기본 이해
설치
지엑스피1
구성
.env.example기반으로.env파일을 만듭니다.
- Claude Desktop 통합의 경우:
서버는 Claude Desktop 구성 파일에서 구성할 수 있습니다.
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
중요 참고 사항:
- 상대 경로가 아닌 절대 경로를 사용하세요.
- Windows에서는 경로에 이중 백슬래시(\\)를 사용합니다.
- 구성 변경 후 Claude Desktop을 다시 시작하세요.
용법
기본 사용법
사용 가능한 도구
- get-file
- Figma 파일 세부 정보 검색 GXP5
- 목록 파일
- Figma 프로젝트 GXP6의 파일 목록
- 변수 생성
- GXP7 디자인 시스템 변수 생성
- 테마 만들기
- GXP8 테마 생성 및 구성
API 문서
서버 방법
startServer(figmaToken: string, debug?: boolean, port?: number)- MCP 서버를 초기화하고 시작합니다.
- 반품: 약속
도구 스키마
모든 도구 입력은 Zod 스키마를 사용하여 검증됩니다.
오류 처리
서버는 자세한 오류 메시지와 적절한 오류 코드를 제공합니다.
- 잘못된 토큰: 특정 오류 메시지가 포함된 403
- 속도 제한: 재설정 시간이 있는 429
- 유효성 검사 오류: 필드별 세부 정보가 포함된 400
- 서버 오류: 오류 추적을 포함한 500개
제한 사항 및 알려진 문제
API 제한
- 읽기 전용 작업
- Figma API 제한으로 인해 읽기 전용 작업으로 제한됨
- 개인 액세스 토큰은 쓰기 작업이 아닌 읽기 작업만 지원합니다.
- 개인 토큰을 사용하여 REST API를 통해 변수, 구성 요소 또는 스타일을 수정할 수 없습니다.
- 쓰기 작업에는 Figma 플러그인 개발이 필요합니다.
- 속도 제한
- Figma API 속도 제한을 따릅니다.
- 더 나은 처리를 위해 지수 백오프를 구현합니다.
- 캐시 관리
- 기본 5분 TTL
- 500개 항목으로 제한됨
- 캐시 무효화 후크 구현을 고려하세요
- 입증
- 개인 액세스 토큰만 지원합니다.
- 팀 수준 권한 또는 공동 편집 지원 없음
- 향후 OAuth 구현 계획
- 기술 구현
- 구성에 절대 경로가 필요합니다.
- 실행 전에 TypeScript 파일을 컴파일해야 합니다.
- 로컬 및 글로벌 모듈 해결을 모두 처리해야 합니다.
기여하다
- 저장소를 포크하세요
- 기능 브랜치 생성
- 테스트를 통해 변경하세요
- 풀 리퀘스트 제출
다음의 코딩 표준을 따라주세요.
- TypeScript 엄격 모드
- ESLint 구성
- 테스트를 위한 농담
- 포괄적인 오류 처리
특허
MIT 라이선스 - 자세한 내용은 라이선스 파일을 참조하세요.
문제 해결
포괄적인 문제 해결 가이드는 TROUBLESHOOTING.md를 참조하세요.
일반적인 문제
- JSON 연결 오류
- Claude Desktop 구성에서 절대 경로 사용
- 서버가 빌드되었는지 확인하세요(
npm run build) - 모든 환경 변수가 설정되었는지 확인하세요
- 인증 문제
- Figma 액세스 토큰이 유효한지 확인하세요
- 토큰에 필요한 권한이 있는지 확인하세요
- 구성에서 토큰이 올바르게 설정되었는지 확인하세요.
- 서버가 시작되지 않음
- Node.js 버전 확인(18.x 이상 필요)
- 빌드가 존재하는지 확인하세요(
dist/index.js) - Claude Desktop 로그 확인:
- macOS:
~/Library/Logs/Claude/mcp*.log - Windows:
%APPDATA%\Claude\logs\mcp*.log
- macOS:
더 자세한 디버깅 단계와 솔루션은 문제 해결 가이드를 참조하세요.
지원하다
- GitHub 문제: 버그 보고
- 문서: 위키
- Discord: 커뮤니티에 가입하세요
You must be authenticated.
Tools
Model Context Protocol을 통해 Figma와 원활하게 상호 작용할 수 있으므로 LLM 애플리케이션이 Figma 파일, 구성 요소 및 변수에 액세스하고 이를 조작하고 추적할 수 있습니다.
- Project Status
- Features
- Prerequisites
- Installation
- Configuration
- Usage
- API Documentation
- Error Handling
- Limitations & Known Issues
- Contributing
- License
- Troubleshooting
- Support