velog-mcp

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

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

참고: 이 프로젝트는 Velog의 비공식 GraphQL API를 사용합니다. Velog의 공식 프로젝트가 아닙니다.

주요 기능

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

빠른 시작

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "velog": {
      "command": "npx",
      "args": ["-y", "velog-mcp"]
    }
  }
}

Claude Code

claude mcp add velog -- npx -y velog-mcp

Cursor / Windsurf

MCP 설정에 동일하게 추가:

{
  "mcpServers": {
    "velog": {
      "command": "npx",
      "args": ["-y", "velog-mcp"]
    }
  }
}

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

도구 목록

인증 불필요

도구	설명	주요 파라미터
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?
edit_post	기존 글 수정	id, title?, body?, tags?, is_private?
delete_post	글 삭제	id

인증

방법 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'이라는 제목으로 글 써줘"
"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

주의사항

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

라이선스

MIT