Figma MCP 연동 시 발생하는 403 Forbidden 오류 대처 방법

 

Figma MCP 403 Forbidden 오류 대처하기 최근 MCP 서버에 피그마를 연동하다가 권한 오류로 막히셨나요? 토큰 발급부터 환경 변수 설정까지, 차근차근 원인을 짚어보고 문제를 풀어나가는 과정을 정리해 보았습니다.

 

요즘 LLM이나 AI 에이전트 환경에 MCP(Model Context Protocol)를 연결해서 피그마(Figma) 디자인 데이터를 직접 읽어오는 시도를 많이들 하시죠. 저도 최근에 피그마 MCP 서버를 로컬에 세팅하다가 뜬금없이 403 Forbidden 에러를 마주하고 꽤나 당황했던 기억이 납니다. "분명히 시키는 대로 토큰을 넣었는데 왜 접근이 안 되지?" 하면서 말이죠.

서버 로그를 열어보면 403 에러가 붉은 글씨로 찍혀 있는데, 이 에러는 보통 서버가 요청을 이해하긴 했지만 권한이 없어서 거부할 때 발생해요. 피그마 연동에서는 십중팔구 토큰(Token)의 스코프(권한)가 부족하거나, 복사하는 과정에서 형식이 틀어졌거나, 이미 만료된 경우랍니다. 오늘은 제가 이 문제를 어떻게 하나씩 확인하고 풀어나갔는지, 그 트러블슈팅 과정을 공유해 보려고 해요. 똑같은 오류로 답답해하시는 분들께 조금이나마 실질적인 도움이 되었으면 좋겠네요. 😊

 

첫 번째 의심: 토큰 권한(Scope) 설정이 맞을까? 🤔

피그마에서 발급받는 Personal Access Token(PAT)은 내 계정의 어떤 데이터에 접근할 수 있는지 '범위(Scope)'를 지정하게 되어 있어요. 403 에러가 났다면, 가장 먼저 이 스코프 설정을 의심해봐야 합니다. 단순히 토큰만 발급받았다고 해서 모든 파일에 접근할 수 있는 건 아니거든요.

MCP 서버가 피그마 파일의 노드(Node) 정보나 텍스트, 컴포넌트 데이터를 읽어오려면 최소한 파일 읽기 권한이 필수적입니다. 종종 토큰을 생성할 때 기본값으로 두거나, 필요한 체크박스를 놓치는 경우가 많아요.

💡 알아두세요!
피그마 토큰은 한 번 생성하고 나면 나중에 권한을 수정할 수 없어요. 만약 권한이 부족해서 발생한 문제라면, 기존 토큰을 지우고 필요한 권한을 체크하여 새로 발급받아야 합니다.

 

Figma 토큰 권한 체크리스트 📊

피그마 계정 설정의 'Personal access tokens' 메뉴에서 새 토큰을 만들 때, 여러 가지 권한 항목이 나타납니다. MCP 서버 연동 시 주로 확인해야 할 항목들을 표로 정리해 보았습니다.

File content 항목의 Read-only 권한은 절대로 빠지면 안 되는 핵심 요소입니다.

토큰 스코프(Scope) 주요 항목

항목 (Scope)	설명	MCP 필요 여부	비고
File content	피그마 파일 내부의 레이어, 텍스트 등 데이터 읽기	필수 (Read-only)	이게 없으면 무조건 403 에러 발생
Comments	파일 내 댓글 읽기 및 쓰기	선택 사항	댓글 분석 기능이 필요할 때만 체크
Webhooks	파일 변경 알림 등 이벤트 수신	일반적으론 불필요	단순 쿼리용 MCP 서버라면 불필요
Team data	팀 프로젝트 및 멤버 정보 접근	상황에 따라 다름	특정 팀 공간 검색 시 필요할 수 있음

⚠️ 주의하세요!
발급받은 토큰 문자열(예: figd_...로 시작)은 화면을 벗어나면 다시 확인할 수 없습니다. 안전한 비밀번호 관리자나 로컬 환경 변수 파일에 즉시 복사해 두는 것을 잊지 마세요.

 

토큰 형식 확인 및 입력 테스트 🧮

스코프를 제대로 설정해서 발급받았는데도 안 된다면, 이제 환경 변수(Environment Variables) 설정 쪽을 들여다봐야 합니다. Claude Desktop의 mcp.json이나 Node.js 로컬 서버의 .env 파일에 토큰을 입력할 때, 혹시 앞뒤로 공백이 들어가진 않았는지 확인해 보세요. 은근히 복사/붙여넣기 실수로 발생하는 에러가 많답니다.

📝 올바른 환경 변수 설정 예시 (mcp.json)

{
  "mcpServers": {
    "figma-server": {
      "command": "node",
      "args": ["/path/to/figma/mcp/build/index.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_aB1c...여러분의토큰..."
      }
    }
  }
}

아래에서 간단히 여러분이 복사한 토큰 문자열의 형식이 기본적인 피그마 토큰 패턴(figd_로 시작하는지, 공백이 없는지)에 맞는지 자가 진단해 볼 수 있습니다.

🔢 토큰 형식 자가 진단기

토큰 문자열:

진단 결과:

조치 사항:

 

기타 원인: 토큰 만료 및 파일 권한 👩‍💼👨‍💻

형식도 맞고 Scope도 다 체크했는데 여전히 막힌다면, 토큰의 '만료 기한(Expiration)' 설정을 확인해 봐야 해요. 피그마에서 토큰을 만들 때 보안을 위해 만료일을 30일, 90일 등으로 짧게 설정할 수 있거든요. 기간이 지난 토큰은 자동으로 폐기되므로 403 에러를 뱉어냅니다.

또한, 간혹 회사 계정이나 프라이빗 워크스페이스(Private Workspace)의 파일을 불러오려 할 때 에러가 날 수 있어요. 내 계정 자체가 해당 파일에 접근할 권한이 없는 뷰어(Viewer) 상태이거나, 외부 서드파티 앱의 접근을 제한하는 보안 정책이 걸려 있는 경우가 그렇습니다. 이럴 땐 브라우저로 해당 피그마 링크에 직접 들어가서 정상적으로 파일이 열리는지 먼저 확인해 보는 것이 좋아요.

📌 알아두세요!
조직(Organization) 요금제를 사용하는 경우, 관리자가 외부 API 접근을 차단했을 수도 있습니다. 개인 워크스페이스에 빈 파일을 하나 만들어놓고 연동 테스트를 먼저 진행해 보세요.

 

실전 예시: 제가 겪었던 트러블슈팅 사례 📚

제 생각엔 실제 사례를 공유해 드리는 게 이해하시기 가장 좋을 것 같아요. 제가 처음 연동을 시도했을 때 겪었던 과정입니다.

사례 주인공의 상황

• 상황 1: Claude Desktop에 @modelcontextprotocol/server-figma를 연동함.
• 상황 2: 피그마 링크를 주며 화면을 요약해달라고 했으나 403 Forbidden 응답이 돌아옴.

원인 파악 과정

1) 첫 번째 단계: mcp.json 파일을 열어 오타나 공백이 있는지 점검했어요. (문제 없음)

2) 두 번째 단계: 피그마 웹사이트 설정에 들어가 발급해둔 토큰을 확인해 보니, 무심코 급하게 만드느라 File content 스코프에 체크를 안 했던 것을 발견했습니다.

최종 결과

- 조치 사항: 기존 토큰을 'Revoke'하고, 권한을 제대로 체크하여 새로 토큰을 발급받아 환경 변수에 재입력함.

- 결과: 에러가 사라지고 LLM이 피그마 프레임 안의 텍스트와 레이어 구조를 정상적으로 읽어오기 시작했습니다.

결국 컴퓨터는 거짓말을 하지 않더라고요. 사소한 설정 하나를 놓쳤던 게 원인이었습니다. 여러분도 당황하지 마시고, 설정들을 차분히 복기해 보시길 권해드립니다.

 

마무리: 핵심 내용 요약 📝

지금까지 Figma API를 MCP와 연동할 때 만나는 403 Forbidden 오류의 원인과 해결 방법을 살펴보았습니다.

💡

Figma MCP 403 에러 요약

✨ 핵심 1: Scope 확인 File content(Read-only) 권한이 반드시 체크되어 있어야 합니다.

📊 핵심 2: 토큰 형식 점검 오타나 공백 없이 환경 변수에 figd_... 형태로 정확히 기입되었는지 확인하세요.

🧮 핵심 3: 만료일 체크

만료된 토큰 폐기 -> 새 토큰 발급 -> 서버 재시작

👩‍💻 핵심 4: 접근 권한 프라이빗 워크스페이스나 조직 계정일 경우, 내 계정 자체가 파일에 접근 가능한지 웹에서 테스트해보세요.

설정을 바꾼 후에는 반드시 MCP 클라이언트(서버)를 재시작해야 적용됩니다.

자주 묻는 질문 ❓

Q: 토큰을 발급받은 뒤 다시 볼 수 있나요?

A: 아니요, 피그마 정책상 생성 직후 한 번만 보여집니다. 잊어버렸다면 기존 것을 지우고 새로 만들어야 합니다.

Q: 401 Unauthorized와 403 Forbidden의 차이가 뭔가요?

A: 401은 토큰 자체가 유효하지 않거나 인증되지 않은 상태이고, 403은 토큰은 맞지만 해당 리소스를 읽을 권한(Scope 등)이 부족한 상태를 뜻합니다.

Q: 토큰 수명은 만료 없음(No expiration)으로 해도 되나요?

A: 설정 자체는 가능하지만 보안상 권장하지 않습니다. 로컬 환경 테스트 용도로는 괜찮지만, 실무 환경에서는 만료 기한을 두는 것이 좋습니다.

Q: 환경 변수를 고쳤는데도 에러가 나요.

A: Claude Desktop이나 Node 서버를 완전히 종료(Quit)한 뒤 재시작해야 새로운 환경 변수가 로드되어 적용됩니다.

Q: 피그마 링크 포맷은 어떻게 넘겨줘야 하나요?

A: 보통 https://www.figma.com/file/[파일ID]/... 혹은 https://www.figma.com/design/[파일ID]/... 형식의 URL을 그대로 전달하면 MCP가 알아서 ID를 파싱하여 처리합니다.

에러 메시지가 떴을 때는 당황하기 쉽지만, 하나하나 체크하다 보면 결국 원인을 찾을 수 있습니다. 오늘 내용이 피그마와 MCP 연동 과정에서 막힌 부분을 뚫어주는 단서가 되길 바랍니다. 이 외에도 환경 설정이나 연동 과정에서 더 궁금한 점이 있다면 언제든 편하게 댓글로 물어봐주세요~ 😊