velog-mcp

# velog-mcp

[![npm](https://img.shields.io/npm/v/@milcho0604/velog-mcp)](https://www.npmjs.com/package/@milcho0604/velog-mcp)
[![Node](https://img.shields.io/badge/node-%3E%3D22.18-brightgreen)](https://nodejs.org)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Runtime deps](https://img.shields.io/badge/runtime%20deps-2-lightgrey)](package.json)

An MCP server for [Velog](https://velog.io), the Korean developer blogging platform.
Read your blog, draft posts, publish them, and back everything up — from Claude or any
MCP client.

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

---

## Why another one?

Two Velog MCP servers already exist. This one differs in three ways.

**1. Publishing is a permission, not a default.**
Out of the box the server can create drafts and publish **privately**. Public
publishing requires you to set an environment variable. The model cannot flip that
switch — only you can, in your MCP config.

**2. Every quirk is measured, not assumed.**
Velog's GraphQL API is undocumented. This repo records what it *actually* does,
verified against [velog-io/velog](https://github.com/velog-io/velog) source and live
calls. Six server-side quirks are written up in
[docs/api-reference.md](docs/api-reference.md) — including one that silently returns an
empty list, and one that can turn your published posts private.

**3. Two runtime dependencies.** `@modelcontextprotocol/sdk` and `zod`. HTTP, test
runner, and TypeScript execution all come from Node itself.

---

## Install

Requires **Node.js 22.18 or newer**. What runs is the compiled `dist/index.js`, but development and verification execute `.ts` directly, and 22.18 is the first release where that works without a flag. CI covers 22.18, 24 and 26.

### As a Claude Code plugin (recommended)

```bash
/plugin marketplace add milcho0604/velog-mcp
/plugin install velog@milcho
```

Installation asks for four values. **Leave them all blank and it still installs,
running read-only.**

| Prompt | If left blank |
| --- | --- |
| Velog refresh token | Read-only (browse, search, stats still work) |
| Allow public publishing | Drafts and private publishing only |
| Allow profile edits | Profile tools stay off |
| Chrome path | Found automatically in standard locations |

**The token goes into the macOS Keychain**, not into a settings file in plaintext.
Only values declared `sensitive: true` reach the Keychain, and a test enforces
that declaration (P7).

Change values later with `/plugin manage`.

### As a plain MCP server

Published on npm, so nothing to clone — your MCP client runs it via `npx`. See
[Configure](#configure) for the config block and the client-support note.

```bash
claude mcp add velog -e VELOG_REFRESH_TOKEN=your_refresh_token \
  -- npx -y @milcho0604/velog-mcp@0.6.1
```

The token stays in your client's config file here. The plugin route above puts it in
the Keychain instead.

### From source

```bash
git clone https://github.com/milcho0604/velog-mcp.git
cd velog-mcp
npm install && npm run build
```

## Configure

Add this to your MCP client config (`claude_desktop_config.json`, `.mcp.json`, …):

```json
{
  "mcpServers": {
    "velog": {
      "command": "npx",
      "args": ["-y", "@milcho0604/velog-mcp@0.6.1"],
      "env": {
        "VELOG_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}
```

With the Claude Code CLI:

```bash
claude mcp add velog -e VELOG_REFRESH_TOKEN=your_refresh_token \
  -- npx -y @milcho0604/velog-mcp@0.6.1
```

To run a local checkout instead, swap the command for
`node /absolute/path/to/velog-mcp/dist/index.js`.

> **Which clients can run this?** This is a stdio server: the client starts it as a
> local process. That works in Claude Code, Claude Desktop, Cursor, and other clients
> that run MCP servers locally. It does **not** work in the claude.ai or ChatGPT web
> apps — both accept only remote MCP servers reachable over HTTP, since the connection
> originates from their servers rather than your machine. Using it there would mean
> hosting it publicly and handing your Velog token to that deployment, which defeats
> the point of keeping the token on your own machine.

### Getting your token

Velog has no public write API, so the server authenticates with your browser session
cookie.

1. Log in at [velog.io](https://velog.io)
2. Open DevTools (`F12`) → **Application** → **Cookies** → `https://velog.io`
3. Copy the value of **`refresh_token`**

**`VELOG_REFRESH_TOKEN` alone is enough.** Velog's server reissues the short-lived
`access_token` on its own ([`authPlugin.mts`](https://github.com/velog-io/velog/blob/main/apps/server/src/common/plugins/global/authPlugin.mts)),
and this server picks the refreshed cookie out of the response. One paste lasts
**30 days**.

`VELOG_ACCESS_TOKEN` also works but expires in about an hour by itself.

> Tokens are read from the environment only. They are never written to disk, and the
> server never reads your browser's cookie database or your OS keychain.
> Whatever you put in your MCP config file does live there in plain text, though —
> that file is yours to protect.

**Without a token the server still starts**, read-only. Public posts, search, trending,
and blog stats all work unauthenticated.

---

## Permissions

| Environment | What you get |
| --- | --- |
| *(nothing set)* | Read everything · create drafts · **publish privately** · draw and upload images — 21 tools |
| `VELOG_ALLOW_PUBLIC=1` | …plus **public publishing** (adds an `is_private` parameter) |
| `VELOG_ALLOW_PROFILE=1` | …plus **profile editing** (adds 5 tools) |

The two switches are independent — enable either, both, or neither.

```json
"env": {
  "VELOG_REFRESH_TOKEN": "...",
  "VELOG_ALLOW_PUBLIC": "1",
  "VELOG_ALLOW_PROFILE": "1"
}
```

Accepted as "on": `1`, `true`, `yes`, `on`. Anything else is off — a typo won't quietly
enable it.

When public publishing is off, the `is_private` parameter **does not exist** on any
tool, so the model has no way to ask for it. When it's on, `is_private` appears and
still defaults to `true`.

### Why private-by-default

Not caution for its own sake. Velog's rate limiter counts only `is_private: false`
posts:

```ts
// apps/server/src/services/PostApiService/index.mts
count({ where: { fk_user_id, is_private: false, released_at: { gt: fiveMinutesAgo } } })
if (count >= 10) {
  updateMany({ where: { fk_user_id, released_at: { gt: fiveMinutesAgo } },
               data: { is_private: true } })   // flips *everything* recent to private
}
```

Private posts don't **increment** that count. But `isPostLimitReached()` runs
unconditionally, *before* privacy is examined — so if ten public posts already exist in
the last five minutes, even a private draft request can trigger the sweep. "Doesn't
increment" is not "can't trigger." That's why write retries stay disabled and the local
limiter stays in place.

Public posts do increment it, and once a post is public it has already gone out through
RSS, search indexes, and subscriber email, none of which a delete reaches. That
asymmetry is what deserves an explicit opt-in.

Full reasoning: [docs/security.md](docs/security.md)

---

## Tools

21 tools. Only 9 of them change anything on Velog.

### Reading — no auth required

| Tool | Purpose |
| --- | --- |
| `velog_get_post` | Read one post, body included |
| `velog_list_posts` | A user's posts, optionally filtered by tag |
| `velog_search_posts` | Keyword search; pass `username` to search inside one blog |
| `velog_trending_posts` | Trending by `day` / `week` / `month` / `year` |
| `velog_recent_posts` | Newest posts across Velog |
| `velog_get_user` | Profile, follower counts, bio |
| `velog_list_series` | A user's series, with post counts and IDs |
| `velog_user_tags` | Tags a user writes about, with counts |

### Reading — auth required

| Tool | Purpose |
| --- | --- |
| `velog_whoami` | Which account the token belongs to (also a token health check) |
| `velog_list_drafts` | Your saved drafts, with IDs |

### Derived — things Velog doesn't provide

| Tool | Purpose |
| --- | --- |
| `velog_blog_stats` | Aggregate views/likes/comments, top posts, per-year and per-tag breakdown |
| `velog_export_posts` | Save posts as Markdown files with YAML front matter |

### Writing

| Tool | Effect |
| --- | --- |
| `velog_create_draft` | Save a draft. Never publishes, under any configuration |
| `velog_update_draft` | Replace a draft **entirely** — omitted fields are reset |
| `velog_publish_post` | Publish a new post |
| `velog_publish_draft` | Publish an existing draft, reusing its stored body |
| `velog_unpublish_post` | Send a published post back to drafts |
| `velog_update_post` | Edit a published post — omitted fields are **kept** |

> `velog_update_draft` resets what you omit; `velog_update_post` preserves it.
> The asymmetry is deliberate — see [docs/tools.md](docs/tools.md).

#### Automatic thumbnail

Omit `thumbnail` and the **first image in the body** becomes the thumbnail, so list and
share cards aren't text-only. What was chosen is always reported back, along with the
other candidates when there is more than one.

| `thumbnail` | Behaviour |
| --- | --- |
| omitted | first image in the body |
| a URL | used as given |
| `null` | **opt out** — leave it empty on purpose |

Images inside code fences and inline code are excluded, so a markdown example never
becomes your thumbnail. `velog_update_post` **never replaces an existing thumbnail** —
editing a title should not change the card. There, `null` means "don't fill it in",
not "delete it".

#### Series — by name, in one call

Pass `series_name` and the server resolves it **before** saving, then sends the id in the
**same request** — writing and filing happen in one call. Names are matched ignoring case
and surrounding whitespace; `series_id` wins if you know it.

⚠️ **If the name isn't found, nothing is written** — saving without the series would look
like it worked. The available series are listed in the error.

Omit both and