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

구성

1. .env.example 기반으로 .env 파일을 만듭니다.

2. Claude Desktop 통합의 경우:

서버는 Claude Desktop 구성 파일에서 구성할 수 있습니다.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

중요 참고 사항:

• 상대 경로가 아닌 절대 경로를 사용하세요.

• Windows에서는 경로에 이중 백슬래시(\\)를 사용합니다.

• 구성 변경 후 Claude Desktop을 다시 시작하세요.

용법

기본 사용법

사용 가능한 도구

1. get-file

   • Figma 파일 세부 정보 검색 GXP5

2. 목록 파일

   • Figma 프로젝트 GXP6의 파일 목록

3. 변수 생성

   • GXP7 디자인 시스템 변수 생성

4. 테마 만들기

   • GXP8 테마 생성 및 구성

API 문서

서버 방법

• startServer(figmaToken: string, debug?: boolean, port?: number)

  • MCP 서버를 초기화하고 시작합니다.

  • 반품: 약속

도구 스키마

모든 도구 입력은 Zod 스키마를 사용하여 검증됩니다.

오류 처리

서버는 자세한 오류 메시지와 적절한 오류 코드를 제공합니다.

• 잘못된 토큰: 특정 오류 메시지가 포함된 403

• 속도 제한: 재설정 시간이 있는 429

• 유효성 검사 오류: 필드별 세부 정보가 포함된 400

• 서버 오류: 오류 추적을 포함한 500개

제한 사항 및 알려진 문제

API 제한

1. 읽기 전용 작업

   • Figma API 제한으로 인해 읽기 전용 작업으로 제한됨

   • 개인 액세스 토큰은 쓰기 작업이 아닌 읽기 작업만 지원합니다.

   • 개인 토큰을 사용하여 REST API를 통해 변수, 구성 요소 또는 스타일을 수정할 수 없습니다.

   • 쓰기 작업에는 Figma 플러그인 개발이 필요합니다.

2. 속도 제한

   • Figma API 속도 제한을 따릅니다.

   • 더 나은 처리를 위해 지수 백오프를 구현합니다.

3. 캐시 관리

   • 기본 5분 TTL

   • 500개 항목으로 제한됨

   • 캐시 무효화 후크 구현을 고려하세요

4. 입증

   • 개인 액세스 토큰만 지원합니다.

   • 팀 수준 권한 또는 공동 편집 지원 없음

   • 향후 OAuth 구현 계획

5. 기술 구현

   • 구성에 절대 경로가 필요합니다.

   • 실행 전에 TypeScript 파일을 컴파일해야 합니다.

   • 로컬 및 글로벌 모듈 해결을 모두 처리해야 합니다.

기여하다

1. 저장소를 포크하세요

2. 기능 브랜치 생성

3. 테스트를 통해 변경하세요

4. 풀 리퀘스트 제출

다음의 코딩 표준을 따라주세요.

• TypeScript 엄격 모드

• ESLint 구성

• 테스트를 위한 농담

• 포괄적인 오류 처리

특허

MIT 라이선스 - 자세한 내용은 라이선스 파일을 참조하세요.

문제 해결

포괄적인 문제 해결 가이드는 TROUBLESHOOTING.md를 참조하세요.

일반적인 문제

1. JSON 연결 오류

   • Claude Desktop 구성에서 절대 경로 사용

   • 서버가 빌드되었는지 확인하세요( npm run build )

   • 모든 환경 변수가 설정되었는지 확인하세요

2. 인증 문제

   • Figma 액세스 토큰이 유효한지 확인하세요

   • 토큰에 필요한 권한이 있는지 확인하세요

   • 구성에서 토큰이 올바르게 설정되었는지 확인하세요.

3. 서버가 시작되지 않음

   • Node.js 버전 확인(18.x 이상 필요)

   • 빌드가 존재하는지 확인하세요( dist/index.js )

   • Claude Desktop 로그 확인:

     • macOS: ~/Library/Logs/Claude/mcp*.log

     • Windows: %APPDATA%\Claude\logs\mcp*.log

더 자세한 디버깅 단계와 솔루션은 문제 해결 가이드를 참조하세요.

지원하다

• GitHub 문제: 버그 보고

• 문서: 위키

• Discord: 커뮤니티에 가입하세요