{
  "markdown": "# planvortex-mcp\n\n[![smithery badge](https://smithery.ai/badge/taliasoftworks/planvortex)](https://smithery.ai/servers/taliasoftworks/planvortex)\n\nThe official [Model Context Protocol](https://modelcontextprotocol.io) server for\n[PlanVortex](https://planvortex.com). It lets an AI assistant — Claude Desktop, Claude Code, Cursor,\nVS Code — schedule posts, read the comment inbox and answer private messages across twelve social\nnetworks: Facebook, Instagram, Threads, LinkedIn, TikTok, X, WhatsApp, YouTube, Google Business,\nBluesky, Discord and Telegram.\n\n> **You need a PlanVortex app, and every plan has them — the free one included.**\n> The server authenticates with a `client_id` and a `client_secret` that you create in the\n> PlanVortex panel under Settings → Apps. How many apps you get is what changes with the plan:\n> 1 on Free, 2 on Basic, 5 on Pro, 10 on Custom.\n\n## Install\n\nNothing to install: your MCP client starts it with `npx`.\n\n### Claude Desktop, Cursor, VS Code\n\n```json\n{\n    \"mcpServers\": {\n        \"planvortex\": {\n            \"command\": \"npx\",\n            \"args\": [\"-y\", \"planvortex-mcp\"],\n            \"env\": {\n                \"PLANVORTEX_CLIENT_ID\": \"...\",\n                \"PLANVORTEX_CLIENT_SECRET\": \"...\",\n                \"PLANVORTEX_ORGANIZATION_ID\": \"optional, but saves a call per conversation\"\n            }\n        }\n    }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add planvortex \\\n  --env PLANVORTEX_CLIENT_ID=... \\\n  --env PLANVORTEX_CLIENT_SECRET=... \\\n  -- npx -y planvortex-mcp\n```\n\nThen ask for something: _\"what do I have scheduled this week, and which comments are still\nunread?\"_\n\n## What it can do\n\nTwenty-eight tools, grouped by what they act on — and a twenty-ninth, `create_ai_plan`, that you\nswitch on yourself (see [Generating with AI](#generating-with-ai)).\n\n| Group      | Tools                                                                                                   |\n| ---------- | ------------------------------------------------------------------------------------------------------- |\n| Context    | `list_organizations`, `list_accounts`, `get_plan_use`, `get_unread_counts`                              |\n| Publishing | `list_publications`, `get_publication`, `create_publication`, `update_publication`, `retry_publication` |\n| AI planner | `get_planner_templates`, `list_ai_plans`, `get_ai_plan`, and `create_ai_plan` when enabled              |\n| Media      | `upload_media`                                                                                          |\n| Comments   | `list_comments`, `get_comment_thread`, `reply_to_comment`, `hide_comment`, `mark_comment_read`          |\n| Messages   | `list_conversations`, `list_messages`, `send_message`                                                   |\n| Numbers    | `get_dashboard_summary`, `get_publication_stats`, `get_top_publications`, `get_account_metrics`         |\n| Catalog    | `get_social_limits`, `get_social_capabilities`, `create_connect_link`                                   |\n\nPlus three prompts — `weekly_plan`, `inbox_triage`, `publish_from_brief` — and four resources with\nthe per-network limits, capabilities, comment matrix and your organizations.\n\n### Generating with AI\n\nPlanVortex does not just schedule what you wrote: it can **write the week for you**. Its planner\nturns a theme, your own photos, an article or a connected shop's catalogue into a week of posts, and\n`get_planner_templates` publishes the five templates with what each one costs.\n\nReading is always available. **Creating a plan is not, unless you switch it on:**\n\n```json\n\"env\": { \"PLANVORTEX_MCP_ALLOW_AI\": \"1\" }\n```\n\nThat is deliberate, and it is about your money rather than your safety. Generating a plan spends AI\ncredits from your account, and an agent that retries in a loop is the worst possible caller for an\nendpoint that bills. The protocol's own answer to this — asking you to confirm from inside the\nserver — is implemented by almost no client yet, so the confirmation is this line instead: a person\nwrites it once, before any agent starts. With it absent, `create_ai_plan` is not in the tool list at\nall, so nothing can call it.\n\nTwo more things worth knowing. `create_ai_plan` **does not return posts**: it queues the plan and\nreturns the budget, and generation takes minutes — poll `get_ai_plan`. And what comes out are\n**drafts**; scheduling them is still a person's decision, one post at a time, through\n`update_publication`.\n\n### Two things it deliberately cannot do\n\n**It never deletes anything.** No tool removes a post, an account, a contact or a comment. This is\nnot a switch you can turn on; the code is not there. The reason is in the security section below.\n\n**It cannot connect a social account.** Connecting Instagram is an OAuth flow with a person clicking\n\"authorize\" on Meta's own screen, and an app with client credentials cannot do that — nobody's app\ncan. `create_connect_link` returns a single-use link that expires in fifteen minutes; hand it to the\nuser and let them open it.\n\n## Security\n\nThis server runs on your machine with your app's `client_secret` inside the process, and it feeds a\nlanguage model text that **members of the public wrote** — comments, reviews, DMs — while that same\nmodel holds tools that publish under your brand.\n\nThat is a prompt-injection surface by construction, and it is worth knowing how it is handled:\n\n- Every comment, review and incoming message arrives wrapped in an `untrusted_content` block with an\n  explicit notice that it is data, not instructions. It is not a guarantee — no wrapper is — but it\n  raises the bar.\n- **No destructive tools.** If an injection succeeds, the worst case is a post you can see and\n  delete, not four thousand deleted contacts.\n- Third-party text never enters a tool description or a cached resource, where your client would not\n  mark it as untrusted.\n- Whether a publish is confirmed by a human is decided by your MCP client, not by this server. The\n  tools declare the annotations that make clients show the warning; keep them on.\n\nSet `PLANVORTEX_MCP_READ_ONLY=1` to remove the nine write tools from the listing entirely — useful\nif you want to give an unsupervised agent read access and nothing else.\n\n### The `--http` mode\n\n`planvortex-mcp --http` serves MCP over HTTP for a self-hosted deployment. **The process holds your\n`client_secret`**, so anything that can reach the port can publish to your accounts with a plain\n`curl`. Therefore:\n\n- it binds to `127.0.0.1` by default;\n- binding anywhere else **requires** `PLANVORTEX_MCP_AUTH_TOKEN` and the server refuses to start\n  without it;\n- the `Origin` header is validated on every request (DNS rebinding);\n- TLS is your reverse proxy's job — put one in front;\n- and a token from the request is never forwarded to PlanVortex. It authenticates against this\n  process and stops here.\n\n```bash\ndocker run --rm -p 127.0.0.1:3000:3000 \\\n  -e PLANVORTEX_CLIENT_ID=... -e PLANVORTEX_CLIENT_SECRET=... \\\n  -e PLANVORTEX_MCP_AUTH_TOKEN=$(openssl rand -hex 32) \\\n  planvortex-mcp --http --host 0.0.0.0\n```\n\nThe flags are not optional there: **the image speaks stdio by default**, because that is what\nan MCP client starts (`docker run -i planvortex-mcp`) and what a server directory introspects.\n`--http` is the deployment mode, and you ask for it.\n\n## Environment variables\n\n| Variable                     | Required                   | What it does                                                   |\n| ---------------------------- | -------------------------- | -------------------------------------------------------------- |\n| `PLANVORTEX_CLIENT_ID`       | yes                        | The app from your account. Every plan has apps.                |\n| `PLANVORTEX_CLIENT_SECRET`   | yes                        | Its secret. Never passed as a tool argument.                   |\n| `PLANVORTEX_ORGANIZATION_ID` | no                         | Default organization. Saves a discovery call per conversation. |\n| `PLANVORTEX_BASE_URL`        | no                         | Point at another PlanVortex deployment.                        |\n| `PLANVORTEX_MCP_UPLOAD_DIRS` | no                         | Directories `upload_media` may read from. Empty means none.    |\n| `PLANVORTEX_MCP_AUTH_TOKEN`  | with `--http` off-loopback | Bearer token the HTTP endpoint requires.                       |\n| `PLANVORTEX_MCP_READ_ONLY`   | no                         | `1` removes the nine write tools.                              |\n| `PLANVORTEX_MCP_ALLOW_AI`    | no                         | `1` adds `create_ai_plan`, which spends AI credits.            |\n| `PLANVORTEX_MCP_LOG_LEVEL`   | no                         | `debug`, `info`, `warn`, `error`, `silent`. Always to stderr.  |\n\n### Uploading media\n\nWith stdio the server runs on your machine, so `upload_media` accepts an **absolute local path** —\nbut only inside `PLANVORTEX_MCP_UPLOAD_DIRS`, which is empty by default. Set it to the folders you\nactually want reachable:\n\n```\nPLANVORTEX_MCP_UPLOAD_DIRS=/Users/you/Pictures,/Users/you/Downloads\n```\n\nReading an arbitrary path is exactly what an injected prompt would ask for, so there is no way to\ndisable the allowlist. In `--http` mode a local path is refused outright: it would be a path on the\nserver, not on your machine. Pass a public https URL there.\n\n## Which organization?\n\nAlmost everything in PlanVortex hangs off an organization. The server resolves it in three steps:\nthe `id_organization` argument if the model passed one, then `PLANVORTEX_ORGANIZATION_ID`, and\nfinally — only if your app reaches exactly one — that one. If it reaches several and nothing says\nwhich, the tool answers with the list of names and ids so the model can retry correctly, rather than\nfailing with a bare error.\n\n## Development\n\n```bash\nnpm install\nnpm test          # layers 1 and 2: no network, no credentials\nnpm run build\nnpm run inspector # MCP Inspector against the built server\n```\n\nBuilt on [`planvortex`](https://www.npmjs.com/package/planvortex), the official Node client. This\nserver speaks no HTTP of its own: every call goes through the library, which is where the error\ncatalogue, the token cache, the multipart upload and the pagination already live.\n\n## Links\n\n- [PlanVortex for developers](https://planvortex.com/en/developers)\n- [`planvortex` for Node](https://www.npmjs.com/package/planvortex) · [`planvortex` for Python](https://pypi.org/project/planvortex/)\n- [Security policy](SECURITY.md) · [Changelog](CHANGELOG.md)\n\nMIT © Talia Softworks\n",
  "bytes": 10518,
  "sha": "53149af57751504a0360de294a755bf105cb6fd960fc48bc9167d331080f836f",
  "repo_slug": "taliasoftworks/planvortexmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_taliasoftworks_planvortex_3f51504d/readme"
}