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 버튼을 눌러 적용합니다.

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

도구 목록

인증 불필요

인증 필요

인증

방법 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) > 미인증 (읽기 전용)

토큰 만료

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

사용 예시

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

로컬 마크다운 파일 발행 (publish_local_markdown) 사용법

로컬에 작성한 마크다운 파일(.md)을 읽어와서 자동으로 제목과 태그를 파싱한 뒤 Velog에 바로 게시할 수 있습니다.

1. 마크다운 파일 형식 (YAML Frontmatter 지원)

게시글의 메타데이터(제목, 태그, 썸네일, 공개 여부)를 설정하기 위해 파일 상단에 YAML 형식의 Frontmatter를 추가하거나, 일반 마크다운 파일처럼 첫 번째 H1 헤더(# 제목)로 제목을 설정할 수 있습니다.

예시 1: YAML Frontmatter 적용 (권장)

---
title: "나의 첫 번째 MCP 블로그 글"
tags: [MCP, Velog, AI]
is_private: false
thumbnail: "https://example.com/thumbnail.png"
---

여기에 본문 내용을 작성합니다.

예시 2: 일반 마크다운 형식

# 나의 첫 번째 MCP 블로그 글

여기에 본문 내용을 작성합니다.

이 경우 제목은 나의 첫 번째 MCP 블로그 글로 설정되며 본문에서는 해당 제목 헤더가 자동으로 제외되어 깔끔하게 등록됩니다.

2. 에이전트 호출 명령 예시

Antigravity 에디터 대화창 또는 MCP 클라이언트에 다음과 같이 요청해 보세요.

• "로컬 경로 /Users/ddukddi/notes/my_post.md 파일을 읽어서 Velog에 포스팅해줘"

• "내 마크다운 파일 /path/to/file.md 내용을 블로그 형식으로 다듬은 다음에 Velog에 발행해줘"

플랫폼 지원

자동 로그인은 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로 바로 등록할 수 있도록 개선했습니다.

• 로컬 마크다운 파일 직접 발행 기능 추가 (publish_local_markdown): 로컬 경로에 있는 .md 파일을 읽어 Velog 글을 작성할 수 있는 기능을 추가했습니다. 마크다운 파일 상단의 YAML Frontmatter 정보(title, tags, thumbnail, is_private) 또는 첫 번째 H1 헤더(# 제목)를 자동으로 파싱하여 글 제목 및 태그로 연동합니다.

주의사항

• Velog의 비공식 GraphQL API를 사용하며, API 변경 시 동작하지 않을 수 있습니다.

• 이 프로젝트는 Velog와 무관한 커뮤니티 프로젝트입니다.

• 과도한 API 호출은 자제해주세요.

라이선스

MIT