velog-mcp

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 with a single command or tool call.

한국어 문서 (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.

Related MCP server: velog-mcp

Installation

# 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 in your browser, open DevTools → Application/Storage → Cookies, and copy the value of the access_token cookie.

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

Verify it works:

velog-mcp auth-check

CLI Usage

# 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:

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

Available MCP tools:

Development

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

License

MIT — see LICENSE.