milcho0604/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 플러그인으로 (권장)
설치할 때 값 네 개를 묻는다. **하나도 안 넣어도 설치되고, 읽기 전용으로 동작한다.**
| 물어보는 것 | 안 넣으면 |
| --- | --- |
| Velog refresh token | 읽기 전용 (조회·검색·통계는 그대로) |
| 공개 발행 허용 | 초안과 비공개 발행까지만 |
| 프로필 수정 허용 | 프로필 도구가 꺼짐 |
| 크롬 경로 | 표준 위치에서 자동으로 찾는다 |
**토큰이 macOS 키체인에 들어간다.** 설정 파일에 평문으로 남지 않는다 —
sensitive: true 로 선언한 값만 키체인으로 가고, 그건 테스트가 강제한다(P7).
값을 나중에 바꾸려면 /plugin manage.
그냥 MCP 서버로
npm 에 올려뒀으니 클론할 것 없이 MCP 클라이언트가 npx 로 띄운다. 설정 블록과
클라이언트 지원 범위는 설정 을 볼 것.
이 방식은 토큰이 클라이언트 설정 파일에 남는다. 위의 플러그인 방식은 키체인에 넣는다.
직접 빌드해서
설정
MCP 클라이언트 설정 파일(claude_desktop_config.json, .mcp.json 등)에 추가한다.
Claude Code CLI 라면:
로컬 체크아웃으로 돌리려면 command 를
node /절대경로/velog-mcp/dist/index.js 로 바꾼다.
> **어떤 클라이언트에서 되나?** 이건 stdio 서버다 — 클라이언트가 로컬 프로세스로 띄운다.
> Claude Code·Claude Desktop·Cursor 처럼 MCP 서버를 로컬에서 실행하는 클라이언트에서 된다.
> **claude.ai 와 ChatGPT 웹앱에서는 안 된다** — 둘 다 HTTP 로 접근 가능한 원격 MCP 서버만
> 받는다. 연결이 내 기계가 아니라 그쪽 서버에서 출발하기 때문이다. 웹에서 쓰려면 서버를
> 공개 호스팅하고 벨로그 토큰을 그 배포본에 넘겨야 하는데, 그러면 토큰을 내 기계에만
> 두려던 이유가 사라진다.
토큰 얻는 법
벨로그는 공개 쓰기 API 가 없어서 브라우저 세션 쿠키로 인증한다.
1. velog.io 에 로그인
2. 개발자도구(F12) → **Application** → **Cookies** → https://velog.io
3. **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개) |
두 스위치는 독립이다 — 하나만 켜도 되고 둘 다 켜도 된다.
'켬'으로 인정하는 값은 1, true, yes, on 뿐이다. 나머지는 전부 꺼짐 —
오타로 조용히 켜지지 않는다.
공개 발행이 꺼져 있으면 어떤 도구에도 is_private 파라미터가 **존재하지 않는다.**
모델이 공개를 요청할 방법 자체가 없다. 켜면 파라미터가 생기지만 기본값은 여전히
true(비공개)다.
왜 비공개가 기본인가
몸사리는 게 아니라 실측 근거가 있다. 벨로그의 발행 제한은 is_private: false 인
글만 센다:
비공개 글은 이 계수를 **올리지 않는다.** 다만 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 | 조회수·좋아요·댓글 집계, 상위 글, 연도별·태그별 분포 |