Velog · LLM Mart

Name: Velog
Author: LLM Mart

No install snippet on purpose. A working MCP config is a command, its arguments and an environment block — the last two are where API keys live, so this catalogue never stores them and cannot publish them. Follow the link above for the authors' own instructions.

벨로그를 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 인 글만 센다: