MCP server that exposes the VibeVO Public API as agent tools, so AI agents (Claude Desktop, IDE agents, custom runners) can discover and operate VibeVO programmatically.

Requires Node.js 20 or later and a VibeVO API key. Uses the stdio transport.

Tools

Version 0.3.0 provides 37 tools.

Tool	Wraps	Scope
`vibevo_whoami`	`GET /public/me`	any valid key
`vibevo_list_offers`	`GET /public/offers`	`read`
`vibevo_list_my_posts`	`GET /public/posts`	`read`
`vibevo_list_campaigns`	`GET /public/campaigns`	`read`
`vibevo_get_campaign`	`GET /public/campaigns/{id}`	`read`
`vibevo_get_campaign_analytics`	`GET /public/analytics/campaigns/{id}`	`read`
`vibevo_list_campaign_posts`	`GET /public/campaigns/{id}/posts`	`read`
`vibevo_list_campaign_creators`	`GET /public/campaigns/{id}/creators`	`read`
`vibevo_list_campaign_tracking_links`	`GET /public/campaigns/{id}/tracking-links`	`read`
`vibevo_get_wallet`	`GET /public/wallet`	`read`
`vibevo_list_wallet_transactions`	`GET /public/wallet/transactions`	`read`
`vibevo_list_factories`	`GET /public/factories`	`read`
`vibevo_get_factory_summary`	`GET /public/factories/{id}/summary`	`read`
`vibevo_list_factory_accounts`	`GET /public/factories/{id}/accounts`	`read`
`vibevo_list_factory_posts`	`GET /public/factories/{id}/posts`	`read`
`vibevo_get_factory_account`	`GET /public/factories/{id}/accounts/{aid}`	`read`
`vibevo_create_factory`	`POST /public/factories`	`write` †
`vibevo_patch_factory`	`PATCH /public/factories/{id}`	`write` †
`vibevo_add_factory_items`	`POST /public/factories/{id}/items`	`write` †
`vibevo_patch_factory_account`	`PATCH /public/factories/{id}/accounts/{aid}`	`write` †
`vibevo_refresh_factory_account`	`POST /public/factories/{id}/accounts/{aid}/refresh`	`write` †
`vibevo_submit_post`	`POST /public/posts`	`write`

Tool	Wraps	Scope
`vibevo_list_factory_tags`	`GET /public/factories/tags`	`read`
`vibevo_list_factory_tag_groups`	`GET /public/factories/{id}/tag-groups`	`read`
`vibevo_get_monitoring_wallet`	`GET /public/factories/credits`	`read`
`vibevo_get_factory_credits`	`GET /public/factories/{id}/credits`	`read`
`vibevo_get_factory_credit_usage`	`GET /public/factories/{id}/credit-usage`	`read`
`vibevo_list_factory_credit_history`	`GET /public/factories/{id}/credit-history`	`read`
`vibevo_update_factory_scan_settings`	`PATCH /public/factories/{id}/credit-settings`	`write` †
`vibevo_set_factory_monitoring`	`POST /public/factories/{id}/monitoring`	`write` †
`vibevo_refresh_factory_post`	`POST /public/factories/{id}/posts/{postId}/refresh`	`write` †
`vibevo_list_factory_reports`	`GET /public/factories/{id}/share-links`	`read`
`vibevo_create_factory_report`	`POST /public/factories/{id}/share-links`	`write` †
`vibevo_revoke_factory_report`	`POST /public/factories/{id}/share-links/{shareId}/revoke`	`write` †
`vibevo_restore_factory_report`	`POST /public/factories/{id}/share-links/{shareId}/restore`	`write` †
`vibevo_delete_factory_report`	`DELETE /public/factories/{id}/share-links/{shareId}`	`write` †
`vibevo_buy_monitoring_tokens`	`POST /public/factories/credits/purchase`	`write` †

Scopes are coarse: read covers every GET, write every mutation. A key always has read; write is granted only if the account has write access. † Content Factories are a separate product feature and their writes must be enabled separately from general write access (they spend money on scraping) — expect 403 if not. vibevo_refresh_factory_account runs a paid scrape and is capped at once per hour per account (429 REFRESH_COOLDOWN, with retryAfterSec). The underlying scanner also requires five minutes after the latest scan recorded in the database, including an automatic scan (429 MONITORING_MANUAL_REFRESH_COOLDOWN, with retryAfterSeconds). tracking_links rows carry uniqueClicks (bot-filtered distinct-device count, not raw hits). There is no test/sandbox mode — all keys are live.

Monitoring contracts

Tags: list tag groups (up to 10 per page), expand accounts with tag, then posts with factoryAccountId. Aggregates cover the full filtered cohort, not just the current page. Tags can overlap; their totals must not be added together.
ER is 100 × (likes + comments) / views, rounded to two decimals; no views means null. Factory, account and tag ER use summed counters, not an average of percentages.
Cadence: intervalHours accepts 24, 12, 10, 8, 6, 4. The tool converts this to scansPerPostPerDay = 24 / intervalHours; ten hours is 2.4, not a rounded integer. trackingDays is 1–365. Resuming monitoring does not force an extra scan.
Token history contains credits/debits, not reservation/release events. Spending is reported for all time, the last 30 days, and today (UTC). Omit the optional factory id on usage/history tools to include all factories and shared-wallet purchases; routes are GET /public/factories/credits/usage and GET /public/factories/credits/history.
Token purchases require explicit user approval (confirm: true). First read pricing with vibevo_get_monitoring_wallet. Reuse the same purchaseId UUID for retries; changing it creates another purchase.
Report creation accepts hiddenFields; omission means all report fields visible. Available fields: views, likes, comments, er, averageViews, medianViews, followers, tags, published, duration, hashtags, contentType, lastScanned, scanState, advertisement, platform, creator, posts, accounts. Hidden source fields also hide derived values/links. Redaction applies server-side to summaries, rows and trends. Row IDs and pagination remain structural; hiding a count does not conceal the existence of enumerable rows. Staff report links remain separate. Save the secret sharePath returned at creation; list responses omit it.

Validation

npm test builds this standalone package and runs a stdio contract test against a loopback HTTP fixture, with a fake key. It never calls production or spends tokens.

Local development

cd mcp
npm install
npm run build

Run

VIBEVO_API_KEY=vibevo_live_xxxxxxxxxxxx.<secret> \
VIBEVO_API_BASE_URL=https://api.vibevo.io \
node dist/index.js

Create an API key in your VibeVO account settings with the permissions the agent needs. Keep the key private; do not commit it to a repository or share it in chat.

Claude Desktop config

Point the client at the npm package via npx (no local checkout needed):

{
  "mcpServers": {
    "vibevo": {
      "command": "npx",
      "args": ["-y", "@vibevo/mcp"],
      "env": { "VIBEVO_API_KEY": "vibevo_live_..." }
    }
  }
}

For local development against a checkout, use the built entrypoint instead:

{
  "mcpServers": {
    "vibevo": {
      "command": "node",
      "args": ["/absolute/path/to/VibeVO/mcp/dist/index.js"],
      "env": { "VIBEVO_API_KEY": "vibevo_live_..." }
    }
  }
}