Allows AI agents to schedule, publish, and analyze social media posts across platforms like TikTok, Instagram, X, and LinkedIn.
Also known as viralnote/mcp-server, mcp-server, @viralnote/mcp-server
- Stars
- 0
- Tools
- 15
- Downloads, 30 days
- —
- Latest version
- 0.2.4
- Last commit
- Oct 21, 2026
- License
- MIT
What is ViralNote MCP?
ViralNote allows AI agents to schedule, publish, and analyze social media posts across platforms like TikTok, Instagram, X, and LinkedIn. It exposes 15 tools, such as list_posts, get_post, create_post.
Summary generated from the project's README
About ViralNote MCP server
ViralNote provides an MCP server that enables AI agents to manage social media presence across numerous platforms including TikTok, Instagram, X, LinkedIn, YouTube, and Reddit. Developers can integrate this server into hosts like Claude Desktop, Claude Code, Cursor, or Cline to allow their agents to perform social media tasks as native tool calls. The server supports both local installation via npm and remote connection through a hosted HTTP server.
Users can manage the entire content lifecycle by using tools like create_post, update_post, and publish_post. The server also handles media management through import_media, which supports files up to 200MB via URL or 3MB via base64 data. To connect, users must provide a VIRALNOTE_API_KEY, which can be generated through the ViralNote developer dashboard. The system also allows for monitoring performance through list_analytics and managing event subscriptions with webhook tools.
What you can do with it
- 1Schedule social media contentAn AI agent can prepare and time a post for a specific platform like Instagram.
Written from the project's README. Every use case is checked against a quote from it.
How to install ViralNote MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall ViralNote MCP in Claude Code
$ claude mcp add --env 'VIRALNOTE_API_KEY=<YOUR_VIRALNOTE_API_KEY>' mcp-server -- npx -y @viralnote/mcp-serverInstall ViralNote MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@viralnote/mcp-server"
],
"env": {
"VIRALNOTE_API_KEY": "<YOUR_VIRALNOTE_API_KEY>"
}
}
}
}Install ViralNote MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@viralnote/mcp-server"
],
"env": {
"VIRALNOTE_API_KEY": "<YOUR_VIRALNOTE_API_KEY>"
}
}
}
}Install ViralNote MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","@viralnote/mcp-server"],"env":{"VIRALNOTE_API_KEY":"<YOUR_VIRALNOTE_API_KEY>"}}'Install ViralNote MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@viralnote/mcp-server"
],
"env": {
"VIRALNOTE_API_KEY": "<YOUR_VIRALNOTE_API_KEY>"
}
}
}
}Install ViralNote MCP in Codex
$ codex mcp add mcp-server --env 'VIRALNOTE_API_KEY=<YOUR_VIRALNOTE_API_KEY>' -- npx -y @viralnote/mcp-serverInstall ViralNote MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-server] command = "npx" args = ["-y", "@viralnote/mcp-server"] [mcp_servers.mcp-server.env] VIRALNOTE_API_KEY = "<YOUR_VIRALNOTE_API_KEY>"
Install ViralNote MCP in Gemini CLI
$ gemini mcp add -s user -e 'VIRALNOTE_API_KEY=<YOUR_VIRALNOTE_API_KEY>' mcp-server npx -- -y @viralnote/mcp-serverInstall ViralNote MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@viralnote/mcp-server"
],
"env": {
"VIRALNOTE_API_KEY": "<YOUR_VIRALNOTE_API_KEY>"
}
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
ViralNote MCP tools 15
Detected from the READMElist_postsget_postcreate_postupdate_postdelete_postpublish_postlist_mediaimport_mediadelete_medialist_social_accountslist_analyticslist_post_results
Show all 15 toolsShow fewer tools
list_webhookscreate_webhookdelete_webhook
Configuration
VIRALNOTE_API_KEYRequiredSecretViralNote API key (create one at https://dashboard.viralnote.app/developers/auth). Format: vnd_...
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHub@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_postswith{ 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_postwith{ 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.
ViralNote MCP questions
How do I add ViralNote MCP to Claude Code?
Run claude mcp add --env 'VIRALNOTE_API_KEY=<YOUR_VIRALNOTE_API_KEY>' mcp-server -- npx -y @viralnote/mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add ViralNote MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does ViralNote MCP provide?
It exposes 15 tools, including list_posts, get_post, create_post, update_post, delete_post.
Which social media platforms are supported?
The server supports X, Instagram, Facebook, TikTok, LinkedIn, YouTube, Pinterest, Bluesky, Threads, and Reddit.
How do I authenticate with the ViralNote MCP server?
You can use OAuth for Gemini CLI and Cline, or provide a VIRALNOTE_API_KEY in your environment variables for Claude Desktop, Cursor, and local installations.
Can I import media from a URL?
Yes, you can import media via URL up to 200MB or via base64 data up to 3MB.