@milcho0604/velog-mcp

velog-mcp

벨로그를 Claude 같은 MCP 클라이언트에서 다루는 서버. 글을 읽고, 초안을 쓰고, 발행하고, 통째로 백업한다.

English →

왜 또 만들었나

벨로그 MCP 서버가 이미 둘 있다. 이 구현은 세 가지가 다르다.

1. 발행은 기본값이 아니라 권한이다. 설치 직후에는 초안 작성과 비공개 발행까지 된다. 공개 발행은 환경변수를 넣어야 열린다. 그 스위치는 모델이 못 건드린다 — MCP 설정 파일을 여는 사람만 바꿀 수 있다.

2. 벨로그 동작을 추측하지 않고 실측했다. 벨로그 GraphQL 은 비공식이라 문서가 없다. 이 레포는 실제로 어떻게 동작하는지를 velog-io/velog 소스와 실호출로 확인해 기록한다. 서버 쪽 함정 6가지가 docs/api-reference.md 에 있다 — 오류 없이 빈 결과를 주는 경우, 발행글을 비공개로 만드는 경우 포함.

3. 런타임 의존성 2개. @modelcontextprotocol/sdk 와 zod 뿐이다. HTTP 와 테스트 러너와 타입스크립트 실행은 전부 Node 내장을 쓴다.

설치

Node.js 22.18 이상이 필요하다. 실행되는 것은 컴파일된 dist/index.js 지만, 개발과 검증이 .ts 를 직접 실행하고 그게 플래그 없이 도는 첫 버전이 22.18 이다. CI 는 22.18 과 24 와 26 에서 돌린다.

Claude Code 플러그인으로 (권장)

/plugin marketplace add milcho0604/velog-mcp
/plugin install velog@milcho

설치할 때 값 네 개를 묻는다. 하나도 안 넣어도 설치되고, 읽기 전용으로 동작한다.

물어보는 것	안 넣으면
Velog refresh token	읽기 전용 (조회·검색·통계는 그대로)
공개 발행 허용	초안과 비공개 발행까지만
프로필 수정 허용	프로필 도구가 꺼짐
크롬 경로	표준 위치에서 자동으로 찾는다

토큰이 macOS 키체인에 들어간다. 설정 파일에 평문으로 남지 않는다 — sensitive: true 로 선언한 값만 키체인으로 가고, 그건 테스트가 강제한다(P7).

값을 나중에 바꾸려면 /plugin manage.

그냥 MCP 서버로

npm 에 올려뒀으니 클론할 것 없이 MCP 클라이언트가 npx 로 띄운다. 설정 블록과 클라이언트 지원 범위는 설정 을 볼 것.

claude mcp add velog -e VELOG_REFRESH_TOKEN=여기에_토큰 \
  -- npx -y @milcho0604/velog-mcp@0.9.5

이 방식은 토큰이 클라이언트 설정 파일에 남는다. 위의 플러그인 방식은 키체인에 넣는다.

직접 빌드해서

git clone https://github.com/milcho0604/velog-mcp.git
cd velog-mcp
npm install && npm run build

설정

MCP 클라이언트 설정 파일(claude_desktop_config.json, .mcp.json 등)에 추가한다.

{
  "mcpServers": {
    "velog": {
      "command": "npx",
      "args": ["-y", "@milcho0604/velog-mcp@0.9.5"],
      "env": {
        "VELOG_REFRESH_TOKEN": "여기에 토큰"
      }
    }
  }
}

Claude Code CLI 라면:

claude mcp add velog -e VELOG_REFRESH_TOKEN=여기에_토큰 \
  -- npx -y @milcho0604/velog-mcp@0.9.5

로컬 체크아웃으로 돌리려면 command 를 node /절대경로/velog-mcp/dist/index.js 로 바꾼다.

어떤 클라이언트에서 되나? 이건 stdio 서버다 — 클라이언트가 로컬 프로세스로 띄운다. Claude Code·Claude Desktop·Cursor 처럼 MCP 서버를 로컬에서 실행하는 클라이언트에서 된다. claude.ai 와 ChatGPT 웹앱에서는 안 된다 — 둘 다 HTTP 로 접근 가능한 원격 MCP 서버만 받는다. 연결이 내 기계가 아니라 그쪽 서버에서 출발하기 때문이다. 웹에서 쓰려면 서버를 공개 호스팅하고 벨로그 토큰을 그 배포본에 넘겨야 하는데, 그러면 토큰을 내 기계에만 두려던 이유가 사라진다.

토큰 얻는 법

벨로그는 공개 쓰기 API 가 없어서 브라우저 세션 쿠키로 인증한다.

• velog.io 에 로그인
• 개발자도구(F12) → Application → Cookies → https://velog.io
• refresh_token 값을 복사

VELOG_REFRESH_TOKEN 하나만 넣으면 된다. 벨로그 서버가 수명 짧은 access_token 을 알아서 재발급하고(authPlugin.mts), 이 서버가 응답에 실려 오는 갱신 쿠키를 받아 쓴다. 한 번 넣으면 30일 간다.

VELOG_ACCESS_TOKEN 도 받지만 단독으로는 1시간이면 만료된다.

토큰은 환경변수로만 읽는다. 디스크에 쓰지 않고, 브라우저 쿠키 DB 나 OS 키체인을 건드리지 않는다. 다만 MCP 설정 파일에 적은 값은 그 파일에 평문으로 남는다 — 그 파일 관리는 사용자 몫이다.

토큰이 없어도 서버는 뜬다. 읽기 전용으로 동작하고, 공개 글 조회·검색·트렌딩· 블로그 통계는 인증 없이 된다.

권한

환경변수	되는 것
(설정 없음)	전체 읽기 · 초안 작성 · 비공개 발행 · 그림 생성·업로드 · 스키마 점검 — 도구 23개
VELOG_ALLOW_PUBLIC=1	…공개 발행 추가 (is_private 파라미터가 생김)
VELOG_ALLOW_PROFILE=1	…프로필 수정 추가 (도구 5개)

두 스위치는 독립이다 — 하나만 켜도 되고 둘 다 켜도 된다.

"env": {
  "VELOG_REFRESH_TOKEN": "...",
  "VELOG_ALLOW_PUBLIC": "1",
  "VELOG_ALLOW_PROFILE": "1"
}

'켬'으로 인정하는 값은 1, true, yes, on 뿐이다. 나머지는 전부 꺼짐 — 오타로 조용히 켜지지 않는다.

공개 발행이 꺼져 있으면 어떤 도구에도 is_private 파라미터가 존재하지 않는다. 모델이 공개를 요청할 방법 자체가 없다. 켜면 파라미터가 생기지만 기본값은 여전히 true(비공개)다.

왜 비공개가 기본인가

몸사리는 게 아니라 실측 근거가 있다. 벨로그의 발행 제한은 is_private: false 인 글만 센다:

// apps/server/src/services/PostApiService/index.mts
count({ where: { fk_user_id, is_private: false, released_at: { gt: 5분전 } } })
if (count >= 10) {
  updateMany({ where: { fk_user_id, released_at: { gt: 5분전 } },
               data: { is_private: true } })   // 최근 글을 '전부' 비공개로
}

비공개 글은 이 계수를 올리지 않는다. 다만 isPostLimitReached() 는 공개 여부를 보기 전에 무조건 실행되므로, 이미 최근 5분에 공개 글이 10건 쌓여 있으면 비공개 초안 요청도 그 파괴 동작을 촉발할 수 있다 — '올리지 않는다'와 '유발하지 않는다'는 다르다. 그래서 쓰기 무재시도와 자체 상한을 함께 유지한다.

공개 글은 계수를 올리고, 한번 공개되면 RSS·검색 색인·구독 메일로 이미 나간 뒤라 지워도 회수가 안 된다. 명시적 opt-in 을 둘 만한 비대칭은 여기에 있다.

자세한 내용: docs/security.md

도구

23개. 벨로그 상태를 바꾸는 건 그중 10개뿐이다.

읽기 — 인증 불필요

도구	하는 일
velog_get_post	글 하나를 본문까지
velog_list_posts	사용자의 글 목록, 태그로 좁힐 수 있음
velog_search_posts	키워드 검색. username 을 주면 그 블로그 안에서만
velog_trending_posts	트렌딩 (day/week/month/year)
velog_recent_posts	벨로그 전체 최신 글
velog_get_user	프로필·팔로워 수·소개
velog_list_series	시리즈 목록 (글 수와 id 포함)
velog_user_tags	사용자가 쓰는 태그와 글 수

읽기 — 인증 필요

도구	하는 일
velog_whoami	토큰이 어느 계정인지 (토큰 생존 확인용으로도)
velog_list_drafts	내 초안 목록과 id

파생 — 벨로그에 없는 기능

도구	하는 일
velog_blog_stats	조회수·좋아요·댓글 집계, 상위 글, 연도별·태그별 분포
velog_export_posts	글을 YAML 프론트매터 붙은 마크다운으로 저장
velog_diagnose	지금 벨로그 스키마가 이 서버의 기준선과 같은지 대조

쓰기

도구	효과
velog_create_draft	초안 저장. 어떤 설정에서도 발행하지 않는다
velog_update_draft	초안 전체 교체 — 생략한 필드는 초기화된다
velog_publish_post	새 글 발행
velog_publish_draft	기존 초안을 발행 (저장된 본문을 그대로 씀)
velog_unpublish_post	발행글을 초안으로 되돌림
velog_update_post	발행글 수정 — 생략한 필드는 유지된다

velog_update_draft 는 생략하면 초기화하고, velog_update_post 는 유지한다. 의도한 비대칭이고 이유는 docs/tools.md 에 있다.

썸네일 자동 채움

thumbnail 을 생략하면 본문 첫 이미지를 썸네일로 쓴다. 목록·공유 카드가 글자만 나오는 걸 막기 위해서다. 무엇을 넣었는지는 결과에 항상 표시하고, 후보가 여럿이면 나머지도 함께 보여준다.

thumbnail 값	동작
생략	본문 첫 이미지로 자동 설정
URL	그대로 사용
null	자동 채움 끄기 — 일부러 비워 두는 경우

코드블록·인라인코드 안의 이미지는 후보에서 제외한다(예제로 적어둔 마크다운이 썸네일이 되면 안 되므로). velog_update_post 는 기존 썸네일이 있으면 덮지 않는다 — 제목만 고쳤는데 목록 카드가 바뀌는 일이 없도록 한 것이고, 이때 null 은 "채우지 마라"이지 "지워라"가 아니다.

시리즈 — 이름으로 한 번에

series_name 에 이름을 주면 저장 전에 내 시리즈에서 찾아 같은 요청에 실어 보낸다. 글쓰기와 시리즈 등록이 한 번의 호출로 끝난다. id 는 사람도 AI 도 모르기 때문에 이름을 받는다.

series_name: "PostgreSQL"     ← 대소문자·앞뒤 공백은 무시하고 찾는다
series_id:   "e53810ca-..."   ← id 를 알면 이쪽이 우선

⚠️ 못 찾으면 글을 저장하지 않는다. 조용히 시리즈 없이 저장하면 들어간 줄 알기 때문이다. 이때 있는 시리즈 목록을 함께 알려준다.

series_name·series_id 를 둘 다 생략하면 저장 뒤 결과에 내 시리즈 목록을 붙여준다. 이 조회가 실패해도 글은 이미 저장된 뒤이므로 저장을 실패시키지 않는다(취소도 삼킨다 — 여기서 실패로 보고하면 재시도 때 글이 두 번 생긴다).

⚠️ 벨로그 API 로는 시리즈를 만들 수 없다. 뮤테이션에 시리즈 관련이 하나도 없고 WritePostInput 도 series_id 만 받는다. 새 시리즈는 벨로그 웹에서 한 번 만들면 그 뒤부터 이 도구로 붙일 수 있다.

username 을 받는 도구 중 velog_list_drafts·velog_blog_stats·velog_export_posts 는 생략하면 내 계정을 쓴다. velog_search_posts 는 생략하면 벨로그 전체를 검색한다.

그림 — 다이어그램·표지

도구	효과
velog_render_diagram	구성도·흐름도를 그려 올린다
velog_render_sequence	참가자와 순서 있는 메시지로 시퀀스 다이어그램을 그린다
velog_render_cover	글 표지 카드(1200×630)를 만든다
velog_upload_image	로컬 이미지를 올리고 마크다운을 돌려준다

넘기는 건 무엇이 있고 무엇이 어디로 흐르는지뿐이다. 색·여백·글자 실측·모서리 라운딩·캔버스 크기는 렌더러가 쥔다. 매번 처음부터 그리면 매번 다르게 생기기 때문이다.

수치는 전부 실측이다. 노드 폭과 줄바꿈은 브라우저 getBBox() 로 잰다 — 글자수로 추정하면 한글·영문이 섞인 라벨에서 반드시 틀린다. 캔버스는 다 그린 뒤에 내용 bbox 로 정하므로 그림이 잘릴 수가 없다.

그리고 스스로 감사해서 여섯 가지를 보고한다:

카드 밖으로 삐져나온 글자 · 억지로 맞추려 눌린 자간
노드를 관통하거나 노드 뒤에 숨은 선 · 그룹 이름표를 가린 선
선끼리 겹침 · 노드끼리 겹침 · 라벨이 카드나 그룹 이름표에 얹히거나 그룹 테두리에 걸침

감사에 하나라도 걸리면 올리지 않는다. 그리고 그걸 끄는 스위치는 없다. 벨로그에는 이미지 삭제 API 가 없고 업로드 한도도 깎이니, 어설픈 그림은 올리는 것보다 고쳐 그리는 게 낫다. 모델이 스스로 켤 수 있는 우회는 방어가 아니다 — 공개 발행 스위치와 같은 이유다(ADR 0004). 감사에 떨어진 PNG 는 이 서버로 올릴 길이 없다. upload:false 로 그려도 그 산출물은 거부 목록에 오르고, 경로를 velog_upload_image 에 줘도 막힌다 — 그 두 단계 우회를 막으려고 만든 장치다. 고쳐서 다시 그리는 것이 유일한 경로다. (감사를 통과한 PNG 는 upload:false 로 그린 뒤 경로를 넘겨 올릴 수 있다.)

아이콘은 내장 28종(server·database·cloud·clock·alert …)이고 전부 도형 조합이다. 밖에서 받아오는 게 하나도 없다 — 렌더러는 DNS 를 막은 채로 돈다.

크롬이 필요하다 (크로미움 계열이면 된다: Edge·Brave·Chromium). macOS·리눅스· 윈도우에서 알아서 찾고, 다른 데 있으면 VELOG_CHROME_PATH 로 지정한다. 이 중 브라우저를 쓰는 건 velog_render_diagram, velog_render_sequence, velog_render_cover 셋뿐이고, velog_upload_image 를 포함한 나머지 19개는 크롬 없이 동작한다.

비용은 실측해서 밝혀 둔다. 그림 한 장에 크롬 911개·최대 약 1GB 를 34초 쓰고 0 으로 돌아온다. 이건 크롬의 바닥이지 우리 그림 탓이 아니다. 좌표·글자·개수에는 전부 상한이 있고, 캔버스 상한(6000px/900만px)은 페이지 안에서 걸린다 — 브라우저는 크기를 받는 순간 표면을 준비하므로 바깥에서 막으면 늦다. 렌더는 줄을 세운다 — MCP 클라이언트가 도구를 병렬로 부르기 때문에, 안 그러면 그림 다섯 장 요청에 크롬 45개·6GB 가 된다. 줄을 세우면 동시 4회도 한 장 분량으로 고정된다. 10회 연속에서 누적이 없는 것도 확인했다.

프로필 수정 — VELOG_ALLOW_PROFILE=1

도구 5개가 추가된다: velog_update_profile(이름·한줄소개), velog_update_about, velog_update_blog_title, velog_update_social_links, velog_update_profile_image. 설정이 없으면 등록조차 되지 않는다.

게이트를 둔 건 위험해서가 아니다 — 전부 되돌릴 수 있고 본인 계정에만 영향이며 어디로도 배포되지 않는다. 이유는 혼동이다: 프로필의 short_bio 와 글의 short_description 은 이름이 비슷하다. "소개 좀 고쳐줘" 가 어느 쪽인지 모호할 때, 스위치가 꺼져 있으면 잘못 짚어도 프로필에 손이 닿지 않는다.

velog_update_profile 은 생략한 항목을 유지한다. 벨로그의 UpdateProfileInput 은 display_name 과 short_bio 를 둘 다 필수로 받아서 한쪽만 보내면 다른 쪽이 빈 문자열로 덮인다 — 그래서 현재 값을 읽어 채워 보낸다.

사용법

설정이 끝나면 MCP 클라이언트에 그냥 말하면 된다.

"오늘 고친 버그로 벨로그 초안 잡아줘"
   → 마크다운을 쓰고 초안으로 저장, 편집 URL 을 준다

"작년에 HTTP/2 로 뭐 썼더라"
   → 내 글 안에서 검색

"내 글 조회수 상위 10개랑 어떤 태그가 제일 많이 읽혔는지"
   → 블로그 전체를 훑어 집계

"내 글 전부 ~/blog-backup 에 백업해"
   → 프론트매터 붙은 .md 로 저장

"그 초안 발행해줘"
   → 기본은 비공개. 공개는 VELOG_ALLOW_PUBLIC=1 이 있어야 한다

"요청이 LB 에서 워커 거쳐 레디스까지 어떻게 흐르는지 그려줘"
   → 그림을 그리고 자가감사한 뒤 올리고, 본문에 붙일 마크다운을 준다

"이 글 표지 이미지 만들어줘"
   → 1200×630 카드. 주소를 velog_update_post 의 thumbnail 에 넣으면 표지가 된다

되돌릴 수 없는 도구에는 destructiveHint 가 붙어 있다. 다만 annotation 은 «힌트» 이지 차단이 아니다 — 호출 전에 승인을 물을지는 MCP 클라이언트 설정에 달렸다. 서버가 막는 것은 따로다: 공개 발행은 VELOG_ALLOW_PUBLIC=1 없이는 경로 자체가 없고, 쓰기는 재시도하지 않으며, 공개 발행은 이 서버 인스턴스 안에서 5분에 5건으로 스스로 제한한다(비공개 발행·초안에는 이 제한이 걸리지 않는다).

백업 파일 형식

---
title: "글 제목"
date: 2022-12-31T18:32:39.790Z
slug: "url-slug"
url: "https://velog.io/@username/url-slug"
tags: ["태그1", "태그2"]
likes: 260
views: 16323
---

마크다운 본문…

개발

npm test              # node:test 로 .ts 직접 실행 — jest·ts-node 없음
npm run typecheck     # 테스트 포함 — 종전엔 제외돼 실제 오류가 숨어 있었다
npm run lint          # typescript-eslint (타입 기반)
npm run build         # tsconfig.build.json (dist 에 테스트 미포함)
npm run schema:dump   # 현재 벨로그 GraphQL 스키마 덤프
npm run schema:baseline  # schema/baseline.json 을 실측으로 다시 만든다 (velog_diagnose 의 기준선)
npm run schema:baseline -- --check   # 쓰지 않고 «지금 기준선이 맞는지» 만 본다

테스트 683건(0.9.5 기준). safety.test.ts 가 보안 불변식(A1A13)을, render.test.ts 가 구성도 불변식(R1R23, D1)과 시퀀스 불변식(S1S12)을, plugin.test.ts 가 포장 불변식(P1P28)을 고정한다. 깨지면 우회하지 말고 왜 깨졌는지부터 볼 것.

여기 있는 방어는 전부 일부러 망가뜨려 확인했다. 소스 변이 54종 + 발행 관문 자체를 겨눈 변이 12종(scripts/gate-mutation.sh), 각각이 검사를 정확히 1건씩 실패시켜야 한다. 방어를 지웠는데도 통과하는 테스트는 테스트가 아니다. 이 저장소에도 그런 게 여럿 있었고, 그렇게 해서 고쳤다.

문서

문서	내용
docs/PRD.md	기획서 — 목표·비목표·성공 기준
docs/architecture.md	구조, Node 타입 스트리핑이 허용하는 TS 부분집합
docs/api-reference.md	벨로그 GraphQL 스키마 실측 + 서버 함정
docs/security.md	토큰 취급, 권한 모델, 의도적으로 뺀 기능
docs/tools.md	도구 카탈로그와 주의사항
docs/decisions/	설계 결정 기록 (ADR)
CHANGELOG.md	버전별로 무엇이 깨져 있었고 무엇이 고쳐졌나

참고

벨로그 내부 GraphQL API 를 쓴다. 비공식이라 예고 없이 바뀔 수 있다. 뭔가 깨지면 npm run schema:dump 를 돌려 docs/api-reference.md 와 diff 하는 게 가장 빠르다.

벨로그 이용약관에는 자동화 접근을 제한하는 조항이 없다. 본인 토큰으로 본인 글을 다루는 것은 권한 내 행위이고, 게시물 저작권은 회원에게 귀속된다(제5조).

라이선스

MIT