velog-mcp

Velog 블로그 플랫폼용 MCP(Model Context Protocol) 서버입니다.

AI 어시스턴트를 통해 Velog 글을 읽고, 검색하고, 작성할 수 있습니다.

참고: 이 프로젝트는 Velog의 비공식 GraphQL API를 사용합니다. Velog의 공식 프로젝트가 아닙니다. 이 프로젝트는 stoneHee99/velog-mcp의 아이디어를 바탕으로 개발되었습니다.

주요 기능

• 글 조회 — 사용자의 글 목록, 상세 내용 조회
• 글 검색 — 키워드 기반 글 검색
• 트렌딩 — 인기 글 조회 (일간/주간/월간)
• 글 작성/수정/삭제 — 마크다운 글 작성, 관리 및 썸네일 연동
• 시리즈/프로필 — 시리즈 목록, 사용자 프로필 조회 및 수정
• 간편 로그인 — Chrome 쿠키 자동 추출로 별도 설정 없이 인증

빠른 시작

Google Antigravity 연동

Antigravity의 MCP 설정 파일(mcp_config.json)에 서버를 등록합니다.

방법 1: UI를 통한 편집

1. Antigravity 에디터의 Agent 사이드 패널을 엽니다.
2. 우측 상단의 ... (더보기) 아이콘을 클릭합니다.
3. Manage MCP Servers를 선택한 후, View raw config를 클릭하여 설정 파일을 엽니다.
4. 아래 설정을 추가합니다.

방법 2: 설정 파일 직접 편집

~/.gemini/antigravity/mcp_config.json (또는 ~/.gemini/antigravity-cli/mcp_config.json) 파일에 다음 설정을 추가합니다.

npm run build를 수행한 후, 생성된 dist/index.js 파일의 절대 경로를 지정해 줍니다.

{
  "mcpServers": {
    "velog": {
      "command": "node",
      "args": ["/absolute/path/to/velog-mcp/dist/index.js"]
    }
  }
}

추가가 완료되면 Manage MCP Servers 메뉴에서 Refresh 버튼을 눌러 적용합니다.

읽기 전용으로 사용할 경우 추가 설정 없이 바로 사용 가능합니다.

도구 목록

인증 불필요

도구	설명	주요 파라미터
get_user_posts	사용자의 글 목록 조회	username, cursor?, limit?
read_post	글 상세 조회 (본문, 댓글 포함)	username, url_slug
get_trending_posts	트렌딩 글 조회	offset?, limit?, timeframe?
search_posts	키워드로 글 검색	keyword, offset?, limit?, username?
get_user_profile	사용자 프로필 조회	username
get_series_list	사용자의 시리즈 목록 조회	username

인증 필요

도구	설명	주요 파라미터
login	Chrome 쿠키에서 토큰 자동 추출	—
write_post	새 글 작성	title, body, tags?, is_private?, url_slug?, series_id?, thumbnail?
edit_post	기존 글 수정	id, title?, body?, tags?, is_private?, thumbnail?
delete_post	글 삭제	id
update_profile	사용자 프로필 수정	display_name?, short_bio?

인증

방법 1: 자동 로그인 (권장)

login 도구를 호출하면:

1. Chrome에 이미 Velog 로그인이 되어 있으면 → 쿠키를 자동으로 읽어 즉시 완료
2. 로그인이 안 되어 있으면 → 기존 Chrome에 새 탭으로 velog.io를 열어줌 → 로그인 후 자동 추출

추출된 토큰은 ~/.velog-mcp/tokens.json에 저장되어 다음 실행 시 자동으로 불러옵니다.

방법 2: 환경변수

{
  "mcpServers": {
    "velog": {
      "command": "npx",
      "args": ["-y", "velog-mcp"],
      "env": {
        "VELOG_ACCESS_TOKEN": "your_access_token",
        "VELOG_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

토큰 확인: velog.io > 개발자 도구 (F12) > Application > Cookies > access_token / refresh_token

토큰 우선순위

환경변수 > 저장 파일 (~/.velog-mcp/tokens.json) > 미인증 (읽기 전용)

토큰 만료

토큰	유효 기간
access_token	1시간
refresh_token	30일

만료 시 login 도구를 다시 호출해주세요.

사용 예시

"이번 주 velog 트렌딩 글 보여줘"
"velopert의 최근 글 목록 알려줘"
"velog에 '오늘의 TIL'이라는 제목으로 글 쓰고 썸네일로 'https://example.com/thumb.png' 지정해줘"
"내 벨로그 프로필의 한 줄 소개를 '매일 성장하는 개발자'로 변경해줘"
"velog에서 TypeScript 관련 글 검색해줘"

플랫폼 지원

기능	macOS	Windows	Linux
읽기 (조회, 검색, 트렌딩)	O	O	O
쓰기 (환경변수 인증)	O	O	O
자동 로그인 (login 도구)	O	O	O

자동 로그인은 Chrome 브라우저가 필요합니다. Windows에서는 sqlite3도 PATH에 설치되어 있어야 합니다.

개발

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

최근 변경 사항

• 프로필 수정 기능 추가 (update_profile): 로그인된 사용자의 이름(display_name) 및 한 줄 소개(short_bio)를 수정할 수 있는 기능을 추가했습니다. 파라미터가 생략된 경우 현재의 프로필 값을 안전하게 유지하며 업데이트합니다.
• 글 작성 및 수정 시 썸네일(Thumbnail) 파라미터 지원: write_post 및 edit_post 도구에 thumbnail 매개변수를 추가하여 글의 커버 이미지를 외부 URL로 바로 등록할 수 있도록 개선했습니다.

주의사항

• Velog의 비공식 GraphQL API를 사용하며, API 변경 시 동작하지 않을 수 있습니다.
• 이 프로젝트는 Velog와 무관한 커뮤니티 프로젝트입니다.
• 과도한 API 호출은 자제해주세요.

라이선스

MIT