# ViralNote MCP Server

ViralNote ships a first-party Model Context Protocol server that exposes the full posting workflow as 32 tools. It supports Streamable HTTP with OAuth 2.0 one-click connect (dynamic client registration + PKCE) or a static API key, and a stdio transport via npm.

## Endpoints

- Streamable HTTP: `https://dashboard.viralnote.app/api/mcp/mcp`
- Server card: `https://www.viralnote.app/.well-known/mcp` · `https://dashboard.viralnote.app/.well-known/mcp/server-card.json`
- OAuth metadata: `https://dashboard.viralnote.app/.well-known/oauth-protected-resource` · `https://dashboard.viralnote.app/.well-known/oauth-authorization-server`
- stdio: `npx -y @viralnote/mcp-server` with `VIRALNOTE_API_KEY=vnd_...` (https://www.npmjs.com/package/@viralnote/mcp-server)
- Documentation MCP server (public, read-only, no auth): `https://www.viralnote.app/mcp/docs` — tools `search_docs`, `get_page`, `list_pages`

## Tools

- `list_brands` — List the brands (workspaces) the account can post as. (scope `posts:read`)
- `list_posts` — List posts filtered by status, platform, brand, or date range. (scope `posts:read`)
- `get_post` — Fetch one post with its per-platform captions, media, and status. (scope `posts:read`)
- `create_post` — Create a draft or scheduled post for one or more platforms. (scope `posts:write`)
- `update_post` — Edit captions, media, platforms, or schedule time of an existing post. (scope `posts:write`)
- `delete_post` — Delete a draft or scheduled post. (scope `posts:write`)
- `publish_post` — Publish a post to its connected accounts right now. (scope `posts:publish`)
- `list_media` — Browse the media library (images, videos, GIFs). (scope `posts:read`)
- `import_media` — Import an image or video into the library from a URL or base64. (scope `posts:write`)
- `delete_media` — Remove a media item from the library. (scope `posts:write`)
- `create_carousel` — Generate a 3–10 slide image carousel as a draft post from a topic or presentation. (scope `credits:write`)
- `list_social_accounts` — List connected social accounts and which platforms are ready to publish. (scope `posts:read`)
- `list_pinterest_boards` — List Pinterest boards available to a connected Pinterest account. (scope `posts:read`)
- `list_usage` — Read shared credit and storage allowances, plus per-brand usage. (scope `credits:read`)
- `get_billing` — Read the plan, trial state, and whether the account can publish or process video. (any credential)
- `start_checkout` — Create a Stripe Checkout link for the account owner to subscribe. Charges nothing by itself. (any credential)
- `top_up_credits` — Create a Stripe Checkout link for a one-time credit pack. (scope `credits:write`)
- `list_analytics` — Read engagement analytics (views, likes, comments, shares) over a date range. (scope `analytics:read`)
- `list_post_results` — Read per-platform publish results and permalinks for posts. (scope `posts:read`)
- `list_webhooks` — List registered webhook endpoints and the events they receive. (scope `webhooks:manage`)
- `create_webhook` — Register a webhook endpoint for post.published, post.failed, and related events. (scope `webhooks:manage`)
- `delete_webhook` — Delete a webhook endpoint. (scope `webhooks:manage`)
- `list_comments` — List comments on published posts, filtered by brand, platform, post, or status. (scope `comments:read`)
- `sync_comments` — Pull the latest comments from connected networks into the inbox. Sends nothing. (scope `comments:read`)
- `reply_to_comment` — Send a public reply to a comment as the connected brand account. (scope `comments:reply`)
- `draft_comment_reply` — Suggest a brand-aware reply for a comment without posting it. (scope `posts:write` or `comments:reply`)
- `update_comment` — Mark a comment handled or reopen it. Local inbox state only. (scope `posts:write`, `comments:reply`, or `comments:moderate`)
- `moderate_comment` — Hide, unhide, delete, or report a comment on the connected network. (scope `comments:moderate`)
- `list_saved_replies` — List a brand's saved replies. (scope `comments:read`)
- `create_saved_reply` — Save a reusable answer for one brand. (scope `posts:write` or `comments:reply`)
- `update_saved_reply` — Edit a saved reply's title or text. (scope `posts:write` or `comments:reply`)
- `delete_saved_reply` — Delete a saved reply. (scope `posts:write` or `comments:reply`)

## Connect

**Claude Code / Claude Desktop (HTTP)**

```json
{ "mcpServers": { "viralnote": { "type": "http", "url": "https://dashboard.viralnote.app/api/mcp/mcp", "headers": { "Authorization": "Bearer vnd_..." } } } }
```

Or add the URL without headers in an OAuth-capable client (Claude, ChatGPT, Cursor) and sign in when prompted.

**stdio**

```json
{ "mcpServers": { "viralnote": { "command": "npx", "args": ["-y", "@viralnote/mcp-server"], "env": { "VIRALNOTE_API_KEY": "vnd_..." } } } }
```

**OpenClaw**

```
openclaw mcp set viralnote '{"url":"https://dashboard.viralnote.app/api/mcp/mcp","transport":"streamable-http","headers":{"x-api-key":"vnd_..."}}'
```

**Hermes** — add under `mcp_servers` in `~/.hermes/config.yaml` with the same URL and `x-api-key` header.

## Where it's listed

- Official MCP Registry: `io.github.viralnote/mcp-server`
- Smithery: https://smithery.ai/servers/viralnote/viralnote
- Cursor Directory: https://cursor.directory/plugins/viralnote
- Glama: https://glama.ai/mcp/servers/viralnote/mcp-server
- Claude plugin: https://github.com/viralnote/claude-plugin

## Auth in one line

Get an API key at https://dashboard.viralnote.app/developers/auth or let the client run OAuth. Scopes: `posts:read`, `posts:write`, `posts:publish`, `comments:read`, `comments:reply`, `comments:moderate`, `analytics:read`, `webhooks:manage`, `credits:read`, `credits:write`. Full walkthrough: https://www.viralnote.app/auth.md

---

Site index for agents: https://www.viralnote.app/llms.txt · Structured view: https://www.viralnote.app/agent.json · API: https://www.viralnote.app/openapi.json · Auth: https://www.viralnote.app/auth.md