@followr/mcp

UNOFFICIAL. Community project maintained by Followr Community Maintainers. Not endorsed by, affiliated with, or supported by Followr Inc. For official Followr support, contact [email protected].

Model Context Protocol (MCP) server for Followr. Connect Claude Desktop, Claude Code, Cursor, or any MCP-compatible AI client to your Followr workspace and operate it from natural language: schedule posts, generate content with AI, manage avatars and lipsync videos, run automations, triage the social inbox, and more.

Status: v0.4.0. API surface is stabilizing; expect occasional changes between minor versions until v1.0.

What you can ask Claude after installing

• "Show me the pending drafts in my Acme workspace."
• "Generate 5 short Instagram caption ideas about [topic] for workspace [name]."
• "Take this blog post URL and adapt it into one post per network for X, LinkedIn, and Instagram, saved as drafts."
• "List all unread DMs across my Facebook and Instagram accounts."
• "Create a short avatar video with [avatar name] saying [script] for Instagram Reels."

The MCP exposes 72 tools, 6 resources, and 5 canned workflows. New since v0.2.0: search_posts_by_topic (semantic search over post history), delete_voice, delete_asset, and get_session_context (one-call orientation). Source code and full tool list at https://github.com/followr-community/followr-mcp.

Before you start

1. A computer (macOS, Windows, or Linux).
2. Node.js 20 or newer. Check with node --version; if missing, install LTS from https://nodejs.org.
3. An MCP-compatible AI client. Pick one:
   • Claude Desktop: https://claude.ai/download (recommended, GUI).
   • Claude Code: https://docs.claude.com/en/docs/claude-code (CLI).
   • Cursor: https://cursor.com (IDE with chat).
4. An active Followr account.

Step 1: Generate a Followr API key

1. Sign in at https://app.followr.ai.
2. Click your profile picture in the top-left corner.
3. Select API Keys from the dropdown menu (shortcut: https://app.followr.ai/settings/api-keys).
4. Click Generate, name it something memorable (e.g. "Claude MCP").
5. Copy the API key immediately. Followr only shows it once.

⚠️ Plan requirement: the Followr API is only available on plans that include API access, or on plans with the API key add-on. If your plan doesn't include it, the MCP installs fine but every call returns 401. Verify or upgrade your plan at https://app.followr.ai first.

⚠️ Security: the API key is a credential. Treat it like a password. Never paste it in a chat (Claude, Slack, anywhere). Only paste it into your terminal or your local config file. If it leaks, revoke it in the same UI and generate a new one.

⚠️ Followr API keys contain a | (pipe) character in the middle. The pipe is a special shell character. In every command below, the API key goes inside single quotes ('...') so the shell does not split it. If you forget the quotes, only the part before the | gets stored and every request returns 401.

Step 2: Configure your AI client

Option A. Claude Desktop (recommended)

Open the config file (create with {} as content if missing):

| OS | Path | |---|---| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

Add the Followr connector inside mcpServers. If your file is {}, replace it with:

{
  "mcpServers": {
    "followr": {
      "command": "npx",
      "args": ["-y", "@followr/mcp"],
      "env": {
        "FOLLOWR_API_TOKEN": "PASTE_YOUR_API_KEY_HERE"
      }
    }
  }
}

If you already have other MCPs, keep them and add "followr" as a sibling:

{
  "mcpServers": {
    "your-existing-mcp": { "...": "..." },
    "followr": {
      "command": "npx",
      "args": ["-y", "@followr/mcp"],
      "env": {
        "FOLLOWR_API_TOKEN": "PASTE_YOUR_API_KEY_HERE"
      }
    }
  }
}

The API key goes inside the JSON string literal as-is (no shell quoting needed inside JSON). The env var name FOLLOWR_API_TOKEN is historical and unchanged for backwards compatibility; the value you paste is your Followr API key.

Save the file, fully quit Claude Desktop (Cmd+Q on macOS, no minimizing), and reopen it. First launch with Followr added takes ~5 to 10 seconds extra to download the package; one-time and cached afterward.

Option B. Claude Code (CLI)

In your terminal, register the MCP at user scope so it is available in every project:

claude mcp add --scope user followr --env 'FOLLOWR_API_TOKEN=PASTE_YOUR_API_KEY_HERE' -- npx -y @followr/mcp

Note: the single quotes around FOLLOWR_API_TOKEN=... protect the | in your token from the shell. Required. Note: --scope user makes it available in every project. Without it, the MCP would only show up in sessions started from the current directory. Note: the -- before npx separates Claude CLI's own arguments from the MCP command.

Verify:

claude mcp get followr

Look for Scope: User config and Status: ✓ Connected. Open a new Claude Code session (existing sessions do not reload MCP config) and try a prompt.

Option C. Cursor

Edit ~/.cursor/mcp.json (or %USERPROFILE%\.cursor\mcp.json on Windows). Use the same JSON shape as Claude Desktop. Restart Cursor.

Step 3: Verify it works

In a new chat, send:

Use the Followr MCP to show me which user my API key belongs to.

Expected response: your name, timezone, language, current credits. If you see that, you are connected.

Troubleshooting

"Failed to connect" right after registering.

Run claude mcp get followr and check the Environment: section. If FOLLOWR_API_TOKEN shows only the first part of your API key (e.g. 220248 without the |... after it), the shell split your command. Re-add with single quotes around the env var:

claude mcp remove followr
claude mcp add --scope user followr --env 'FOLLOWR_API_TOKEN=YOUR_FULL_API_KEY' -- npx -y @followr/mcp

The MCP is registered but my AI client says it does not see it.

Verify the scope. claude mcp get followr should show Scope: User config (private to you across all projects). If it says Scope: Local config (private to you in this project), the MCP is only available in sessions opened from the directory where you ran claude mcp add. Remove and re-add with --scope user.

For Claude Desktop and Cursor, fully quit and reopen the app (do not just close the window).

"Command 'npx' not found."

Node.js is not installed or not on your PATH. Install LTS from https://nodejs.org, then restart your terminal and your AI client.

"401 Unauthorized" on every tool call.

The API key is invalid, revoked, or your plan does not include API access. Generate a new key in Followr (profile picture → API Keys → Generate), verify your plan at https://app.followr.ai, update the value in your config (or via claude mcp remove followr + re-add), and restart your client.

"This user does not belong to the company provided."

You asked the AI to operate on a workspace your API key has no access to. Ask Claude to list your workspaces first and pick one you own or are a member of.

"Your current subscription does not include the necessary features to perform this action."

The specific workspace does not have the AI add-on enabled. Try a workspace on the full plan, or upgrade the workspace's plan in Followr.

First call to the MCP feels slow.

That is npx downloading the package and its runtime dependencies (~25 MB cached in ~/.npm/_npx/). One-time. Subsequent launches are immediate. Pre-warm if you want:

npx -y @followr/mcp --version || true

(Ignore the output; the cache is now warm.)

Security and privacy

• The MCP runs as a local subprocess of your AI client. It is not a hosted service.
• Your Followr API key never leaves your computer except in HTTPS requests directly to api.followr.ai.
• The API key only unlocks the workspaces you already have access to in Followr.
• No telemetry. The MCP does not phone home.
• Source code is open and auditable: https://github.com/followr-community/followr-mcp.
• To revoke a leaked API key: Followr → profile picture → API Keys → delete.

What's not in v0.1

• Remote HTTP transport (planned for v0.2). Today the MCP runs as a local subprocess only.
• A handful of Followr API endpoints we have not verified end-to-end yet (analytics edge cases, some Canva flows).

Where to ask for help

• Bugs in this MCP: https://github.com/followr-community/followr-mcp/issues
• Source code (audit anything): https://github.com/followr-community/followr-mcp
• Unofficial Followr API docs: https://followrapi-docs.pages.dev
• Followr product support (account, billing, features): [email protected]

License

MIT. See LICENSE.