Figma + Notion MCP Server

Figma와 Notion API를 MCP(Model Context Protocol)로 노출하는 Python 서버입니다. Claude Desktop, Cursor 등 MCP 클라이언트에서 Figma 파일·Notion 문서를 직접 조회·편집하고, 자연어로 디자인을 설명하면 Figma에 자동으로 그려주는 기능까지 제공합니다.

---

MCP 엔드포인트

경로	SSE URL	설명
/figma	http://localhost:8000/figma/sse	Figma 파일 읽기 (8개 도구)
/notion	http://localhost:8000/notion/sse	Notion 페이지/DB 조회·편집 (7개 도구)
/project	http://localhost:8000/project/sse	Figma + Notion 통합 조회 (3개 도구)
/draw	http://localhost:8000/draw/sse	자연어 → Figma 디자인 자동 생성 (8개 도구)

---

프로젝트 구조

3-레이어 아키텍처입니다. 의존 방향은 단방향 (mcp → services → core).

main.py                     # FastAPI 앱 — 4개 MCP 서버 마운트
src/
├── core/                   # 인프라 레이어
│   ├── config.py           # 환경변수 → Settings 싱글턴 (frozen dataclass + lru_cache)
│   └── http.py             # figma_client / notion_client async 컨텍스트 매니저
├── services/               # 비즈니스 레이어
│   ├── figma.py            # FigmaService — Figma REST API 호출 + 응답 가공
│   ├── notion.py           # NotionService — Notion API 호출 + 응답 가공
│   └── figma_draw.py       # FigmaDrawService — 디자인 명세 → Figma Plugin Script 생성
└── mcp/                    # 인터페이스 레이어
    ├── figma.py            # figma_mcp + @tool 8개
    ├── notion.py           # notion_mcp + @tool 7개
    ├── project.py          # project_mcp + @tool 3개
    └── draw.py             # draw_mcp + @tool 8개

---

설치 및 실행

1. 패키지 설치

pip install -r requirements.txt

2. 환경변수 설정

cp .env.example .env

.env 파일을 열어 토큰을 입력합니다.

FIGMA_ACCESS_TOKEN=fig_xxxxxxxxxxxxxxxxxxxxxxxx
NOTION_API_KEY=secret_xxxxxxxxxxxxxxxxxxxxxxxx

Figma Personal Access Token 발급

1. figma.com에 로그인합니다.
2. 좌측 상단 프로필 아이콘 클릭 → Settings를 선택합니다.
3. Security 탭으로 이동합니다.
4. Personal access tokens 섹션에서 Generate new token을 클릭합니다.
5. 토큰 이름을 입력하고 (예: mcp-server), 만료 기간을 선택합니다.
6. Scopes는 기본값(File content: Read only)이면 충분합니다.
7. 생성된 fig_ 로 시작하는 토큰을 복사하여 .env의 FIGMA_ACCESS_TOKEN에 붙여넣습니다.

주의: 토큰은 생성 직후에만 표시됩니다. 페이지를 벗어나면 다시 확인할 수 없으므로 바로 복사하세요.

Notion Integration Secret 발급

1. notion.so/my-integrations에 접속합니다.
2. 새 API 통합 만들기 (New integration)를 클릭합니다.
3. 기본 정보를 입력합니다:
   • 이름: 원하는 이름 (예: MCP Server)
   • 연결된 워크스페이스: API로 접근할 워크스페이스 선택
4. 기능 설정:
   • 콘텐츠 읽기: 허용
   • 콘텐츠 업데이트: 허용 (페이지 생성·수정 기능을 쓸 경우)
   • 콘텐츠 삽입: 허용
5. 제출을 클릭하면 secret_으로 시작하는 Internal Integration Secret이 표시됩니다.
6. 토큰을 복사하여 .env의 NOTION_API_KEY에 붙여넣습니다.

중요 — 페이지 연결 필수: Integration을 만들었더라도, 접근할 Notion 페이지/데이터베이스에 직접 연결해야 합니다.

1. 접근할 Notion 페이지를 엽니다.
2. 우측 상단 ··· 메뉴 클릭 → 연결 (Connections)을 선택합니다.
3. 방금 만든 Integration 이름을 검색하여 추가합니다.
4. 하위 페이지에도 접근 허용할지 확인 후 승인합니다.

이 단계를 빠뜨리면 API 호출 시 403 Forbidden 에러가 발생합니다.

3. 서버 실행

python3 main.py

개발 중 자동 재시작:

uvicorn main:app --reload --port 8000

http://localhost:8000/ 에서 전체 엔드포인트 목록을 확인할 수 있습니다.

---

사용자 연동 가이드

MCP 서버가 배포되어 있다면, 아래 설정만으로 바로 사용할 수 있습니다.

아래 예시의 https://your-mcp-server.com을 실제 배포 URL로 바꿔주세요.

Claude Code (CLI)

터미널에서 아래 명령을 실행합니다.

# 필수 (Figma + Notion + 통합)
claude mcp add --transport sse soldoc-figma https://your-mcp-server.com/figma/sse
claude mcp add --transport sse soldoc-notion https://your-mcp-server.com/notion/sse
claude mcp add --transport sse soldoc-project https://your-mcp-server.com/project/sse

# 선택
claude mcp add --transport sse soldoc-draw https://your-mcp-server.com/draw/sse
claude mcp add --transport sse soldoc-asana https://your-mcp-server.com/asana/sse

등록 확인:

claude mcp list

Claude Code 실행 후 /mcp 명령으로 연결 상태를 확인할 수 있습니다.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS)을 열고 mcpServers에 추가합니다.

사전 요구: Node.js 18 이상 (node -v로 확인)

{
  "mcpServers": {
    "soldoc-figma": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-mcp-server.com/figma/sse", "--port", "5011"]
    },
    "soldoc-notion": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-mcp-server.com/notion/sse", "--port", "5012"]
    },
    "soldoc-project": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-mcp-server.com/project/sse", "--port", "5013"]
    },
    "soldoc-draw": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-mcp-server.com/draw/sse", "--port", "5014"]
    },
    "soldoc-asana": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-mcp-server.com/asana/sse", "--port", "5015"]
    }
  }
}

저장 후 Claude Desktop을 완전 종료(Cmd+Q) 후 재시작합니다.

사용 예시

연결 후 Claude에게 이렇게 요청하면 됩니다.

# Figma — URL 붙여넣기만 하면 됩니다
"이 Figma 기획 내용 정리해줘: https://www.figma.com/design/abc123/..."

# Notion
"Notion에서 '스프린트' 키워드로 검색해줘"

# 통합 조회
"Figma 파일과 Notion 페이지로 프로젝트 현황 요약해줘"

# Asana
"Asana 프로젝트 목록 보여줘"
"'로그인 버그 수정' 태스크를 만들고 김철수에게 할당해줘"

# 디자인 생성
"로그인 페이지 디자인을 Figma에 그려줘"

트러블슈팅

증상	원인	해결
Server Disconnected	Node.js 16 이하	Node 18+ 설치, 또는 npx를 절대경로로 변경
Server Disconnected	서버 미실행/접속 불가	서버 URL이 올바른지, 서버가 실행 중인지 확인
포트 충돌	mcp-remote 포트 겹침	각 서버의 --port 값을 다르게 지정
도구가 안 보임	설정 미반영	Claude Desktop 완전 종료(Cmd+Q) 후 재시작
NVM 환경에서 에러	잘못된 Node 버전 참조	"command": "/opt/homebrew/bin/npx" 등 절대경로 사용

---

서버 개발/운영 가이드

아래는 MCP 서버를 직접 실행하거나 개발할 때 참고하는 내용입니다.

로컬 실행

pip install -r requirements.txt
cp .env.example .env   # 토큰 입력
python3 main.py        # http://localhost:8000

로컬에서 Claude Code/Desktop에 연결할 때는 URL을 http://localhost:8000/...으로 사용합니다.

---

도구 목록

/figma — Figma 읽기 (10개)

도구	설명
parse_url	Figma URL에서 file_key, node_id 자동 추출
get_me	내 계정 정보 + 소속 팀 목록
get_file	파일 구조(페이지 목록, 수정일, 썸네일) 조회
get_file_nodes	특정 노드(프레임, 컴포넌트 등) 세부 정보 조회
get_file_components	파일 내 모든 컴포넌트 목록 조회
get_file_styles	색상·텍스트·효과 스타일 목록 조회
get_image_urls	노드 렌더링 이미지 URL 생성 (PNG, SVG, PDF 등)
get_comments	파일에 달린 댓글 전체 조회
get_team_projects	팀의 프로젝트 목록 조회
get_project_files	프로젝트 내 파일 목록 조회

/notion — Notion 읽기/쓰기 (7개)

도구	설명
search_pages	워크스페이스에서 페이지/데이터베이스 검색
get_page	페이지 메타데이터(제목, 속성, URL) 조회
get_page_content	페이지 본문 블록 전체 조회
get_database	데이터베이스 스키마(속성 정의) 조회
query_database	필터·정렬 조건으로 데이터베이스 쿼리
create_page	특정 페이지 하위에 새 페이지 생성
update_page_title	페이지 제목 업데이트

/project — 통합 허브 (8개)

Figma URL을 직접 넣으면 자동 파싱하며, Figma + Notion을 동시에 조회합니다.

도구	설명
parse_figma_url_tool	Figma URL → file_key, node_id 추출
get_my_figma_info	내 Figma 계정/팀 조회
search_all	Figma + Notion 동시 검색
get_figma_file_from_url	Figma URL만으로 파일 구조 + 노드 자동 조회
get_figma_node_from_url	Figma URL의 특정 노드 세부 조회
get_project_overview	Figma + Notion 동시 요약 (URL 직접 입력 가능)
sync_figma_components_to_notion	Figma 컴포넌트 → Notion DB 동기화
get_design_doc_status	Notion DB 작업 상태 집계 + Figma 수정일

/asana — Asana 프로젝트 관리 (11개, 선택)

ASANA_ACCESS_TOKEN 환경변수가 설정되어 있을 때만 활성화됩니다.

도구	설명
get_workspaces	워크스페이스 목록
get_projects	프로젝트 목록
get_project	프로젝트 상세 정보
get_project_sections	섹션(보드 컬럼) 목록
get_tasks	태스크 목록
get_task	태스크 상세 정보
create_task	태스크 생성 (섹션 지정 가능)
update_task	태스크 수정 (이름, 설명, 마감일, 완료 등)
move_task_to_section	태스크 상태(섹션) 변경
assign_task	담당자 지정/변경
get_users	워크스페이스 멤버 목록

/draw — Figma 디자인 자동 생성

자연어로 디자인을 설명하면 Claude가 도구를 호출하고, 반환된 plugin_script를 Figma 콘솔에 붙여넣으면 자동으로 그려집니다.

도구	설명
draw_design	JSON 명세로 완전 자유 형식 디자인 생성
draw_button	버튼 컴포넌트 (primary / secondary / danger / outline)
draw_card	카드 컴포넌트 (선택적 이미지 영역 포함)
draw_navbar	내비게이션 바
draw_login_page	로그인 페이지 전체 레이아웃
draw_dashboard_page	대시보드 페이지 전체 레이아웃
draw_profile_page	프로필 페이지 전체 레이아웃
draw_custom_page	섹션을 자유롭게 구성하는 커스텀 페이지
get_draw_guide	사용 가이드 및 지원 타입 목록 반환

Figma 콘솔에서 실행하는 방법

1. Figma 데스크탑 앱 실행
2. 상단 메뉴 Plugins → Development → Open Console
3. 도구가 반환한 plugin_script 값을 붙여넣기
4. Enter → 현재 페이지에 디자인 생성 완료

---

사용 예시

서버와 Claude Desktop을 연결한 뒤 Claude에게 이렇게 요청할 수 있습니다.

# Figma 분석
"Figma 파일 abc123의 컴포넌트 목록을 보여줘"
"이 Figma 파일에서 색상 스타일을 전부 뽑아줘"

# Notion 작업
"Notion에서 '스프린트' 키워드로 페이지를 검색해줘"
"이 데이터베이스에서 Status가 '진행 중'인 항목만 뽑아줘"

# 통합 조회
"Figma 파일 abc123과 Notion 페이지 def456으로 프로젝트 현황을 요약해줘"
"Figma 컴포넌트 목록을 Notion DB에 동기화해줘"

# 디자인 자동 생성
"소셜 로그인 버튼이 있는 로그인 페이지를 Figma에 그려줘"
"카드 4개짜리 대시보드를 만들어줘"
"파란색 primary 버튼 하나 만들어줘"
"상단 네비바, 프로필 이미지, 이름, 소개, 편집 버튼이 있는 프로필 페이지 그려줘"

---

린트 & 타입 체크

ruff check .          # 린트 검사
ruff check . --fix    # 자동 수정
ruff format .         # 포매팅
mypy src/             # 타입 체크

설정: pyproject.toml (ruff line-length=100, target-version=py311 / mypy strict=true)

---

기술 스택

패키지	역할
FastMCP 2.x	MCP 서버 프레임워크
FastAPI	HTTP 서버 및 라우팅
httpx	비동기 HTTP 클라이언트
uvicorn	ASGI 서버
python-dotenv	.env 파일 로드

---

관련 문서

• CLAUDE.md — Claude Code용 아키텍처·컨벤션·린트 가이드
• CONTEXT.md — 전체 작업 이력, 설계 결정 이유, 미완료 항목 (인수인계용)