# velog-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A Python-based MCP (Model Context Protocol) Server & CLI that lets you
publish, save-as-draft, and back up local Markdown posts — including their
local images — to [Velog](https://velog.io) with a single command or tool
call.

[한국어 문서 (README.ko.md)](README.ko.md)

## Why velog-mcp?

Most existing Velog integrations only forward raw text and silently drop
local images. `velog-mcp` parses Markdown image references
(`![alt](./images/foo.png)`) in your post, automatically uploads each local
image via Velog's v3 storage API
(`https://v3.velog.io/api/files/v3/upload`), and rewrites the links to the
official Velog CDN (`https://velog.velcdn.com/...`) before the post is
written.

- **Local image auto-upload & rewrite** — the core differentiator: no more
  broken image links.
- **Thumbnail upload** support out of the box.
- **Draft-by-default safety net** — posts are saved as a draft
  (`is_temp=True`) unless you explicitly pass `--public` / `is_temp=False`.
- **SHA-256 image cache** — the same image referenced multiple times (or
  reused across posts in one run) is only uploaded once.
- **Two-way backup (pull)** — download your published or draft posts back
  into local Markdown + images.

## Installation

```bash
# Run instantly without installing (recommended)
uvx velog-mcp

# Or install into your environment
pip install velog-mcp
```

## Authentication

`velog-mcp` needs your Velog `access_token` cookie value. It is resolved in
this order:

1. Environment variable `VELOG_ACCESS_TOKEN`
2. `~/.hermes/velog_token.txt`
3. `~/.velog/token`

To obtain the token: log in to [velog.io](https://velog.io) in your browser,
open DevTools → Application/Storage → Cookies, and copy the value of the
`access_token` cookie.

```bash
mkdir -p ~/.velog
echo "your-access-token" > ~/.velog/token
```

Verify it works:

```bash
velog-mcp auth-check
```

## CLI Usage

```bash
# Save as draft (default, safe)
velog-mcp publish ./post.md --tags python,mcp

# Publish immediately
velog-mcp publish ./post.md --tags python,mcp --public

# With a thumbnail, skip local image upload
velog-mcp publish ./post.md --thumbnail ./cover.png --no-upload-images

# List your posts
velog-mcp list --limit 20
velog-mcp list --temp

# Back up a post (Markdown + images) locally
velog-mcp pull my-post-slug --output ./backup
```

Running `velog-mcp` with no subcommand starts the MCP stdio server (same as
`velog-mcp serve`).

## MCP Server (Claude Desktop, etc.)

Add to your Claude Desktop `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "velog": {
      "command": "uvx",
      "args": ["velog-mcp"],
      "env": {
        "VELOG_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}
```

Available MCP tools:

| Tool | Description |
| --- | --- |
| `velog_upload_image` | Upload a local image to Velog's CDN, returns the URL |
| `velog_create_post` | Publish/draft a local Markdown file, auto-uploading local images |
| `velog_list_posts` | List your published or draft posts |
| `velog_get_post` | Fetch a published post's full Markdown body |
| `velog_pull_post` | Back up a post to local Markdown + images |

## Development

```bash
uv venv .venv
uv pip install -e ".[dev]"
.venv/bin/pytest -q
```

## License

MIT — see [LICENSE](LICENSE).