fonts-mcp

v0.1.0

Published

18 days ago

Korean & English Font Catalog MCP Server for Claude Code

0High
0Medium
0Low

moonkey48

Fonts MCP Server

한국어/영문 폰트 카탈로그 MCP 서버입니다. Claude Code에서 폰트 추천, 다운로드, CSS 생성을 자동으로 처리합니다.

빠른 시작 (npm)

사전 준비

아래 두 가지가 설치되어 있어야 합니다.

| 필요 항목 | 설치 확인 방법 | 설치 안내 | |-----------|---------------|----------| | Node.js (v18 이상) | 터미널에서 node --version 입력 | nodejs.org | | Claude Code (CLI 도구) | 터미널에서 claude --version 입력 | claude.ai/claude-code |

등록

터미널에서 아래 명령어 한 줄을 실행하면 끝입니다. 별도 다운로드나 빌드 과정이 없습니다.

claude mcp add fonts-mcp -- npx -y fonts-mcp

이 명령어가 하는 일:

Claude Code에 fonts-mcp라는 MCP 서버를 등록합니다.
npx -y fonts-mcp는 npm에서 패키지를 자동으로 받아서 실행합니다.
이후 Claude Code를 실행할 때마다 자동으로 서버가 시작됩니다.

등록 확인

Claude Code를 실행한 후, /mcp 명령어를 입력하면 등록된 MCP 서버 목록에 fonts-mcp가 표시됩니다.

특정 프로젝트에서만 사용하기

전역이 아닌 특정 프로젝트에서만 사용하려면, 해당 프로젝트 폴더에서 -s project 옵션을 추가합니다.

cd my-project
claude mcp add -s project fonts-mcp -- npx -y fonts-mcp

이렇게 하면 해당 프로젝트의 .mcp.json 파일에 등록됩니다.

사용 가능한 도구

등록이 완료되면 Claude Code 대화 중에 아래 5가지 도구를 사용할 수 있습니다. 직접 도구 이름을 입력할 필요 없이, 자연어로 요청하면 Claude가 적절한 도구를 선택합니다.

1. `list_fonts` — 폰트 목록 조회

등록된 전체 폰트를 조회하거나, 조건별로 필터링합니다.

파라미터:

| 이름 | 필수 | 설명 | 사용 가능한 값 | |------|------|------|---------------| | category | 선택 | 폰트 분류 | sans-serif, serif, display, handwriting, monospace | | language | 선택 | 지원 언어 | ko, en | | useCase | 선택 | 용도 | heading, body, ui, code, logo | | search | 선택 | 이름/태그 검색 | 자유 입력 (예: "프리텐다드", "modern") |

대화 예시:

"한국어 산세리프 폰트 목록 보여줘"
"코딩용 폰트 뭐가 있어?"
"프리텐다드 검색해줘"

2. `recommend_fonts` — 폰트 추천

프로젝트 유형, 용도, 스타일에 맞는 폰트를 점수와 함께 추천합니다. 폰트 페어링(본문+제목 조합)도 함께 제안받을 수 있습니다.

파라미터:

| 이름 | 필수 | 설명 | 사용 가능한 값 | |------|------|------|---------------| | projectType | 선택 | 프로젝트 유형 | landing-page, dashboard, blog, e-commerce, portfolio | | useCase | 선택 | 용도 | heading, body, ui, code, logo | | style | 선택 | 원하는 스타일 | 자유 입력 (예: "modern", "elegant") | | needsPairing | 선택 | 페어링 추천 여부 | true 또는 false |

대화 예시:

"블로그용 폰트 추천해줘"
"대시보드에 쓸 현대적인 폰트 추천해줘. 페어링도 알려줘"
"이커머스 사이트에 맞는 폰트 뭐가 좋을까?"

추천 결과에는 각 폰트의 CSS font-family 값이 포함되어 있어서, 추천 결과를 바로 코드에 적용할 수 있습니다.

3. `get_font_details` — 폰트 상세 정보

특정 폰트의 상세 정보를 확인합니다. 라이선스, 지원 굵기(weight), 다운로드 URL, 추천 페어링 등이 포함됩니다.

파라미터:

| 이름 | 필수 | 설명 | |------|------|------| | fontId | 필수 | 폰트 ID (예: "pretendard", "inter") |

대화 예시:

"Pretendard 상세 정보 보여줘"
"Inter 폰트 라이선스가 뭐야?"
"나눔명조 어떤 weight 지원해?"

4. `download_font` — 폰트 다운로드

선택한 폰트를 GitHub 또는 Google Fonts에서 자동으로 다운로드하여 프로젝트 폴더에 저장합니다.

파라미터:

| 이름 | 필수 | 설명 | 기본값 | |------|------|------|--------| | fontId | 필수 | 폰트 ID | — | | outputDir | 선택 | 저장 경로 | 프레임워크에 따라 자동 결정 (아래 참고) | | formats | 선택 | 원하는 파일 형식 | 폰트별 기본값 (예: ["woff2", "woff"]) | | framework | 선택 | 프로젝트 프레임워크 | "auto" (자동 감지) |

저장 경로 기본값:

| 프레임워크 | 기본 저장 경로 | 이유 | |-----------|---------------|------| | Next.js | ./public/fonts/{fontId}/ | public/ 폴더가 빌드에 포함됨 | | Vite | ./public/fonts/{fontId}/ | public/ 폴더가 빌드에 포함됨 | | 기타 | ./fonts/{fontId}/ | 범용 경로 |

대화 예시:

"Pretendard 다운로드해줘"
"Inter 폰트 woff2 형식으로 다운받아줘"
"나눔명조 public/fonts에 다운로드해줘"

다운로드 후 자동으로 수행되는 작업:

fonts.manifest.json 파일에 설치된 폰트 정보가 기록됩니다.
프로젝트의 CLAUDE.md 파일에 폰트 사용법이 추가됩니다.

이 두 파일에 대한 자세한 설명은 자동 생성 파일 섹션을 참고하세요.

5. `generate_font_css` — CSS 생성

다운로드된 폰트 파일을 기반으로 @font-face CSS 코드를 생성합니다. 파일로 저장하거나, 텍스트로 반환받을 수 있습니다.

파라미터:

| 이름 | 필수 | 설명 | 기본값 | |------|------|------|--------| | fontId | 필수 | 폰트 ID | — | | fontDir | 선택 | 폰트 파일이 있는 폴더 | 프레임워크에 따라 자동 결정 | | cssOutputPath | 선택 | CSS 파일 저장 경로 | 미지정 시 텍스트로 반환 | | fontDisplay | 선택 | font-display 속성값 | "swap" | | framework | 선택 | 프로젝트 프레임워크 | "auto" (자동 감지) |

CSS 경로 처리 방식:

| 프레임워크 | URL 형식 | 예시 | |-----------|---------|------| | Next.js | 절대 경로 (/fonts/...) | url('/fonts/pretendard/Pretendard-400.woff2') | | Vite | 절대 경로 (/fonts/...) | url('/fonts/inter/Inter-400.woff2') | | 기타 | 상대 경로 | url('./fonts/pretendard/Pretendard-400.woff2') |

대화 예시:

"Pretendard CSS 만들어줘"
"Inter 폰트 CSS 파일로 저장해줘. 경로는 src/styles/fonts.css"
"나눔명조 font-display를 optional로 CSS 생성해줘"

생성되는 CSS 예시:

@font-face {
  font-family: 'Pretendard';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url('/fonts/pretendard/Pretendard-Regular.woff2') format('woff2');
}

@font-face {
  font-family: 'Pretendard';
  font-style: normal;
  font-weight: 700;
  font-display: swap;
  src: url('/fonts/pretendard/Pretendard-Bold.woff2') format('woff2');
}

실제 사용 예시

예시 1: "블로그 만들건데 폰트 추천해줘"

Claude와의 대화 흐름:

나: 블로그 만들건데 폰트 추천해줘. 페어링도 같이.

Claude: (recommend_fonts 실행)
  1. Noto Serif KR — CSS: font-family: 'Noto Serif KR', serif;
     페어링 추천: Pretendard
  2. Nanum Myeongjo — CSS: font-family: 'Nanum Myeongjo', serif;
     페어링 추천: Nanum Gothic
  ...

나: Noto Serif KR이랑 Pretendard 둘 다 다운로드해줘

Claude: (download_font 2회 실행)
  Noto Serif KR → public/fonts/noto-serif-kr/
  Pretendard → public/fonts/pretendard/

나: 둘 다 CSS도 만들어줘

Claude: (generate_font_css 2회 실행)
  @font-face CSS 생성 완료

예시 2: "대시보드 프로젝트에 UI 폰트 적용"

나: Next.js 대시보드 프로젝트야. UI용 폰트 추천해줘

Claude: (recommend_fonts 실행)
  1. Inter — CSS: font-family: 'Inter', sans-serif;
  2. Pretendard — CSS: font-family: 'Pretendard', sans-serif;
  ...

나: Inter 다운받고 CSS까지 한번에 해줘

Claude: (download_font → generate_font_css 순차 실행)
  Next.js 감지됨 → public/fonts/inter/ 에 저장
  @font-face CSS 생성 (절대 경로 /fonts/inter/... 사용)

수록 폰트 목록

총 20개의 폰트가 등록되어 있습니다.

한국어 지원 폰트 (12개)

| ID | 이름 | CSS font-family | 분류 | 굵기(Weight) | |----|------|----------------|------|-------------| | pretendard | 프리텐다드 | Pretendard | Sans-serif | 100~900 | | noto-sans-kr | 노토 산스 KR | Noto Sans KR | Sans-serif | 100, 300, 400, 500, 700, 900 | | noto-serif-kr | 노토 세리프 KR | Noto Serif KR | Serif | 200~900 | | spoqa-han-sans-neo | 스포카 한 산스 네오 | Spoqa Han Sans Neo | Sans-serif | 100, 300, 400, 500, 700 | | ibm-plex-sans-kr | IBM 플렉스 산스 KR | IBM Plex Sans KR | Sans-serif | 100~700 | | d2coding | D2코딩 | D2Coding | Monospace | 400, 700 | | gmarket-sans | 지마켓 산스 | GmarketSans | Display | 300, 500, 700 | | nanum-gothic | 나눔고딕 | Nanum Gothic | Sans-serif | 400, 700, 800 | | nanum-myeongjo | 나눔명조 | Nanum Myeongjo | Serif | 400, 700, 800 | | kopub-batang | 코퍼브 바탕 | KoPub Batang | Serif | 300, 500, 700 | | wanted-sans | 원티드 산스 | Wanted Sans | Sans-serif | 100~900 | | suite | 수트 | SUITE | Sans-serif | 300~900 |

영문 폰트 (8개)

| ID | 이름 | CSS font-family | 분류 | 굵기(Weight) | |----|------|----------------|------|-------------| | inter | Inter | Inter | Sans-serif | 100~900 | | roboto | Roboto | Roboto | Sans-serif | 100, 300, 400, 500, 700, 900 | | poppins | Poppins | Poppins | Sans-serif | 100~900 | | playfair-display | Playfair Display | Playfair Display | Serif | 400~900 | | montserrat | Montserrat | Montserrat | Sans-serif | 100~900 | | jetbrains-mono | JetBrains Mono | JetBrains Mono | Monospace | 100~800 | | fira-code | Fira Code | Fira Code | Monospace | 300~700 | | source-code-pro | Source Code Pro | Source Code Pro | Monospace | 200~900 |

참고: CSS font-family 열의 값이 실제 CSS에서 사용해야 하는 정확한 이름입니다. 일부 폰트는 표시 이름과 CSS 이름이 다릅니다. 예를 들어, "Gmarket Sans"의 CSS font-family는 GmarketSans입니다.

프레임워크 자동 감지

download_font과 generate_font_css는 프로젝트 루트의 설정 파일을 확인하여 프레임워크를 자동으로 감지합니다.

| 감지 조건 | 판정 결과 | 동작 | |----------|----------|------| | next.config.js, next.config.mjs, 또는 next.config.ts 존재 | Next.js | public/fonts/에 저장, 절대 경로 CSS | | vite.config.js, vite.config.ts, 또는 vite.config.mjs 존재 | Vite | public/fonts/에 저장, 절대 경로 CSS | | 위 파일이 모두 없음 | 기타 | fonts/에 저장, 상대 경로 CSS |

자동 감지를 무시하고 직접 지정하려면, Claude에게 프레임워크를 명시적으로 알려주면 됩니다:

"Next.js 프로젝트로 설정해서 Pretendard 다운로드해줘"

자동 생성 파일

폰트를 다운로드하면 아래 두 파일이 자동으로 생성/업데이트됩니다.

`fonts.manifest.json`

프로젝트 루트에 생성되며, 설치된 폰트의 메타데이터를 JSON 형식으로 기록합니다.

{
  "version": 1,
  "fonts": [
    {
      "id": "pretendard",
      "fontFamily": "Pretendard",
      "weights": [100, 200, 300, 400, 500, 600, 700, 800, 900],
      "category": "sans-serif",
      "files": ["Pretendard-Regular.woff2", "Pretendard-Bold.woff2"],
      "fontDir": "./public/fonts/pretendard",
      "cssPath": "src/styles/fonts.css",
      "framework": "nextjs",
      "installedAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

이 파일의 용도:

generate_font_css 실행 시 CSS 파일 경로(cssPath)를 자동 업데이트합니다.
프로젝트에서 어떤 폰트가 설치되어 있는지 프로그래밍 방식으로 확인할 수 있습니다.

`CLAUDE.md` 자동 업데이트

프로젝트의 CLAUDE.md 파일에 설치된 폰트 정보가 자동으로 추가됩니다. 이 정보는 다음 Claude Code 세션에서도 유지되므로, Claude가 이전에 어떤 폰트를 설치했는지 기억할 수 있습니다.

추가되는 내용 형식:

## Installed Fonts

<!-- fonts-mcp:pretendard -->
### Installed Font: Pretendard
- CSS: `font-family: 'Pretendard', sans-serif;`
- Weights: 100, 200, 300, 400, 500, 600, 700, 800, 900
- Files: `./public/fonts/pretendard`
<!-- /fonts-mcp:pretendard -->

같은 폰트를 다시 다운로드하면 기존 항목이 업데이트되며, 중복으로 추가되지 않습니다.

로컬 빌드로 설치하기

npm에 배포되기 전이거나, 소스 코드를 수정해서 사용하려는 경우 아래 방법으로 설치할 수 있습니다.

사전 준비

| 필요 항목 | 설치 확인 방법 | 설치 안내 | |-----------|---------------|----------| | Bun (JavaScript 런타임) | 터미널에서 bun --version 입력 | bun.sh | | Claude Code (CLI 도구) | 터미널에서 claude --version 입력 | claude.ai/claude-code |

설치 순서

# 1. 저장소 다운로드
git clone <저장소 URL> fonts-mcp
cd fonts-mcp

# 2. 의존성 설치
bun install

# 3. 빌드
bun run build

# 4. Claude Code에 등록
claude mcp add fonts-mcp -- node /절대경로/fonts-mcp/dist/server.js

등록 후 /mcp 명령어로 fonts-mcp가 표시되는지 확인합니다.

개발

이 프로젝트를 직접 수정하거나 기여하려는 경우를 위한 안내입니다.

빌드

bun run build

테스트

bun test

개발 모드 (파일 변경 시 자동 빌드)

bun run dev

프로젝트 구조

fonts-mcp/
├── src/
│   ├── server.ts              # MCP 서버 진입점 (도구 등록)
│   ├── types.ts               # 타입 정의 (FontEntry, FontSummary 등)
│   ├── catalog/
│   │   ├── fonts.json         # 폰트 카탈로그 데이터 (20개)
│   │   └── loader.ts          # 카탈로그 검색/추천 로직
│   └── tools/
│       ├── list-fonts.ts      # list_fonts 도구
│       ├── recommend-fonts.ts # recommend_fonts 도구
│       ├── get-font-details.ts# get_font_details 도구
│       ├── download-font.ts   # download_font 도구
│       ├── generate-font-css.ts # generate_font_css 도구
│       └── manifest.ts        # 매니페스트/CLAUDE.md 관리
├── test/
│   └── catalog.test.ts        # 카탈로그 테스트
├── dist/                      # 빌드 결과물
├── package.json
├── tsup.config.ts
└── CLAUDE.md                  # Claude Code 프로젝트 설정

폰트 추가하기

새 폰트를 카탈로그에 추가하려면:

src/catalog/fonts.json에 새 항목을 추가합니다.
아래 필드를 모두 포함해야 합니다:

{
  "id": "font-id",
  "name": { "ko": "한국어 이름", "en": "English Name" },
  "fontFamily": "CSSFontFamilyName",
  "category": "sans-serif",
  "weights": [400, 700],
  "languages": ["ko", "en"],
  "license": { "type": "OFL-1.1", "commercial": true },
  "download": {
    "url": "https://...",
    "source": "github",
    "format": ["woff2"]
  },
  "useCases": ["body", "heading"],
  "projectTypes": ["blog", "landing-page"],
  "description": {
    "ko": "한국어 설명",
    "en": "English description"
  },
  "tags": ["modern", "popular"],
  "pairsWith": ["other-font-id"]
}

fontFamily 값은 CSS font-family 속성에서 실제로 사용하는 이름이어야 합니다. 대부분 name.en과 동일하지만, 폰트에 따라 다를 수 있습니다.
bun test를 실행하여 새 항목이 올바르게 추가되었는지 확인합니다.

라이선스

이 MCP 서버 자체의 라이선스는 프로젝트 설정을 따릅니다. 각 폰트의 라이선스는 폰트별로 다르며, get_font_details 도구로 개별 확인할 수 있습니다. 수록된 모든 폰트는 상업적 사용이 가능합니다.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Fonts MCP Server

목차

빠른 시작 (npm)

사전 준비

등록

등록 확인

특정 프로젝트에서만 사용하기

사용 가능한 도구

1. list_fonts — 폰트 목록 조회

2. recommend_fonts — 폰트 추천

3. get_font_details — 폰트 상세 정보

4. download_font — 폰트 다운로드

5. generate_font_css — CSS 생성

실제 사용 예시

예시 1: "블로그 만들건데 폰트 추천해줘"

예시 2: "대시보드 프로젝트에 UI 폰트 적용"

수록 폰트 목록

한국어 지원 폰트 (12개)

영문 폰트 (8개)

프레임워크 자동 감지

자동 생성 파일

fonts.manifest.json

CLAUDE.md 자동 업데이트

로컬 빌드로 설치하기

사전 준비

설치 순서

개발

빌드

테스트

개발 모드 (파일 변경 시 자동 빌드)

프로젝트 구조

폰트 추가하기

라이선스

1. `list_fonts` — 폰트 목록 조회

2. `recommend_fonts` — 폰트 추천

3. `get_font_details` — 폰트 상세 정보

4. `download_font` — 폰트 다운로드

5. `generate_font_css` — CSS 생성

`fonts.manifest.json`

`CLAUDE.md` 자동 업데이트