# velog-mcp

[![npm version](https://img.shields.io/npm/v/velog-mcp)](https://www.npmjs.com/package/velog-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCPAmpel](https://img.shields.io/endpoint?url=https://mcpampel.com/badge/stoneHee99/velog-mcp.json)](https://mcpampel.com/repo/stoneHee99/velog-mcp)

[Velog](https://velog.io) 블로그 플랫폼용 MCP(Model Context Protocol) 서버입니다.

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

> **참고:** 이 프로젝트는 Velog의 비공식 GraphQL API를 사용합니다. Velog의 공식 프로젝트가 아닙니다. 이 프로젝트는 [stoneHee99/velog-mcp](https://github.com/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` 파일의 절대 경로를 지정해 줍니다.

```json
{
  "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?` |
| `publish_local_markdown` | 로컬 마크다운 파일 직접 발행 | `filePath`, `title?`, `tags?`, `is_private?`, `thumbnail?` |

## 인증

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

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

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

### 방법 2: 환경변수

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

토큰 확인: [velog.io](https://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 관련 글 검색해줘"
"로컬 경로 '/Users/ddukddi/notes/my_post.md' 파일을 읽어서 Velog에 포스팅해줘"
```

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

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

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

**예시 1: YAML Frontmatter 적용 (권장)**
```markdown
---
title: "나의 첫 번째 MCP 블로그 글"
tags: [MCP, Velog, AI]
is_private: false
thumbnail: "https://example.com/thumbnail.png"
---

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

**예시 2: 일반 마크다운 형식**
```markdown
# 나의 첫 번째 MCP 블로그 글

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

#### 2. 에이전트 호출 명령 예시
Antigravity 에디터 대화창 또는 MCP 클라이언트에 다음과 같이 요청해 보세요.
* "로컬 경로 `/Users/ddukddi/notes/my_post.md` 파일을 읽어서 Velog에 포스팅해줘"
* "내 마크다운 파일 `/path/to/file.md` 내용을 블로그 형식으로 다듬은 다음에 Velog에 발행해줘"

## 플랫폼 지원

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

> 자동 로그인은 Chrome 브라우저가 필요합니다. Windows에서는 [sqlite3](https://www.sqlite.org/download.html)도 PATH에 설치되어 있어야 합니다.

## 개발

```bash
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](LICENSE)