mcp server

mcp-server

Model Context Protocol server for ViralNote — schedule posts, manage media, read analytics via MCP tools

viralnote/mcp-servercommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

Node.js 20 or newer

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "viralnote-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@viralnote/mcp-server"
      ],
      "env": {
        "VIRALNOTE_API_KEY": "<your VIRALNOTE_API_KEY>"
      }
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 17, 2026

@viralnote/mcp-server

A Model Context Protocol server for the ViralNote social media API.

Plug it into Claude Desktop, Claude Code, Cursor, or any other MCP-aware host and your agent can schedule posts, manage media, and read analytics across X, Instagram, Facebook, TikTok, LinkedIn, YouTube, Pinterest, Bluesky, Threads, and Reddit — as native MCP tool calls. No glue code.

Install

Gemini CLI

Install the extension from this repository:

gemini extensions install https://github.com/viralnote/mcp-server

Restart Gemini CLI, then run /mcp auth viralnote to sign in to your ViralNote account and authorize the connection. The extension uses the hosted HTTP server with OAuth; no API key or local server build is required. Start with a read such as "List my connected social accounts."

Cline

In Cline's MCP Servers screen, add a remote Streamable HTTP server named viralnote at https://dashboard.viralnote.app/api/mcp/mcp, then complete the OAuth sign-in. For the Cline CLI, run:

cline mcp install viralnote --transport http https://dashboard.viralnote.app/api/mcp/mcp

The wizard asks for authentication details before saving. See llms-install.md for the setup walkthrough and API-key alternative. Keep automatic approval disabled and verify the connection with a read before making changes.

Claude Desktop / Claude Code / Cursor

Add to your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, similar on other platforms):

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

Restart your MCP host. The ViralNote tools will be available immediately.

This repo includes a root .mcp.json (Open Plugins standard) so tools like Cursor Directory can auto-detect the MCP server from the GitHub URL.

Cursor Marketplace

Once the plugin is published on Cursor Marketplace, you can install it directly from Cursor:

Open Cursor and go to Settings → Plugins
Search for "ViralNote" in the Marketplace
Click Install
In Plugins → Configure, set your VIRALNOTE_API_KEY
Get your API key from dashboard.viralnote.app or viralnote.app/developers/auth

The ViralNote tools will be immediately available in your Cursor environment.

Local install

npm install -g @viralnote/mcp-server

Then reference viralnote-mcp directly in your MCP config:

{
  "mcpServers": {
    "viralnote": {
      "command": "viralnote-mcp",
      "env": { "VIRALNOTE_API_KEY": "vnd_..." }
    }
  }
}

Configuration

Env var	Required	Default	Notes
`VIRALNOTE_API_KEY`	yes	—	Generate at viralnote.app/developers/auth. Grant `posts:read`, `posts:write`, plus `webhooks:*` if your agent should manage webhooks.
`VIRALNOTE_API_BASE`	no	`https://viralnote.app/api/v1`	Override for staging/self-hosted instances.

Tools exposed

Tool	Purpose
`list_posts`	List posts (filter by status/platform, paginated)
`get_post`	Read one post including per-platform publish results
`create_post`	Create a draft (`is_draft: true`) or scheduled post
`update_post`	Update a draft or scheduled post
`delete_post`	Delete (cancels if scheduled)
`publish_post`	Publish a draft now
`list_media`	List media library items
`import_media`	Import by URL (200MB) or base64 data (3MB)
`delete_media`	Delete a media item
`list_social_accounts`	List connected social accounts
`list_analytics`	Published posts with per-platform metrics
`list_post_results`	Per-platform delivery results (success/error)
`list_webhooks`	List webhook subscriptions
`create_webhook`	Subscribe to events
`delete_webhook`	Unsubscribe

For most users, the HTTP MCP server at https://viralnote.app/api/mcp/mcp is simpler than installing this stdio package — see https://viralnote.app/developers/mcp for the HTTP config snippet. Use this stdio package when your MCP client doesn't support HTTP transport.

The underlying REST endpoints and request/response shapes are documented at viralnote.app/developers/docs.

Example agent prompts

"Show me my last 5 scheduled posts." Tool: list_posts with { status: "scheduled", limit: 5 }.

"Schedule this caption to Instagram for tomorrow at 9am, attaching the photo I uploaded yesterday." Tools: list_media → find item → create_post with { platforms: ["instagram"], caption, libraryItemId, scheduledFor, status: "scheduled" }.

"Pull this Dropbox link into my library, then publish it to X immediately." Tools: import_media → create_post (draft) → publish_post.

Development

git clone https://github.com/viralnote/mcp-server
cd mcp-server
npm install
npm run build
VIRALNOTE_API_KEY=vnd_... npm start

For local iteration without rebuilding:

VIRALNOTE_API_KEY=vnd_... npm run dev

License

MIT — see LICENSE. Pull requests welcome.