Velog
Read and write Velog (velog.io), the Korean developer blog. Public publishing is opt-in.
벨로그를 Claude 같은 MCP 클라이언트에서 다루는 서버. 글을 읽고, 초안을 쓰고, 발행하고, 통째로 백업한다.
왜 또 만들었나
벨로그 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 인
글만 센다:
From the project's README.