socialvault-mcp

A Model Context Protocol server that exposes SociaVault's Reddit and YouTube voice-extraction endpoints as natural-language tools inside Claude Desktop. It pulls raw first-person customer voice (Reddit comment threads, YouTube comments) that gets pasted into Deep Research avatar briefs — content Deep Research can't fetch directly (Reddit returns SITE_BLOCKED; YouTube comments are JS-loaded).

Spelling, on purpose: the vendor is SociaVault, host api.sociavault.com (no "L"). This repo is socialvault-mcp (with an "L"). Both are intentional — don't "correct" either.

Tools

| Tool | Status | What it returns | |------|--------|-----------------| | reddit_subreddit_search | required | Posts (or comments/media) in one subreddit — title, url, score, real created_iso, cursor. | | reddit_post_comments | required | A post's comment tree flattened with depth, verbatim body, created_iso, permalink. Deleted/removed/empty dropped by default. selftext kept separate with a marketing caution. | | youtube_video_comments | required | Comments with verbatim content, likes, date_relative, creator/verified flags. Creator self-promo dropped by default. No absolute date (synthetic on this endpoint). | | reddit_search | optional | Cross-subreddit post search. Docs-based schema, not live-verified. | | youtube_search | optional | Topic → video URLs. Docs-based schema, not live-verified. |

Normalization (why this isn't a passthrough)

The raw API responses are large, noisy, and contain traps. This server:

• Un-object-keys data.comments / data.posts / replies.items — the API returns these as objects keyed by stringified integers ("0", "1", …), not arrays. They're coerced to arrays in numeric order.
• Flattens the Reddit reply tree into one ordered list with a depth field.
• Drops non-content: [deleted]/[removed]/empty Reddit comments (keep_deleted to retain) and the channel's own YouTube creator comments, which are reliably pinned promo (keep_creator to retain, flagged).
• Refuses to fabricate dates: YouTube absolute timestamps are synthetic, so only the trustworthy relative date is emitted, with a date_note. Reddit dates are real and passed through as created_iso.
• Flags rather than drops verified (non-creator) YouTube accounts — a verified commenter can be a real person.
• Surfaces failures honestly as { ok: false, http_status, api_error, endpoint }. It never synthesizes content to fill a request.

Install

npm install
npm run build   # -> dist/index.js

Claude Desktop config

{
  "mcpServers": {
    "socialvault": {
      "command": "node",
      "args": ["/absolute/path/to/socialvault-mcp/dist/index.js"],
      "env": { "SOCIAVAULT_API_KEY": "the-key" }
    }
  }
}

The server fails fast with a clear message (not a stack trace) if SOCIAVAULT_API_KEY is missing. The key is never logged. Each API call costs 1 credit; credits_used is passed through on every response.

Known limitations

Response size is bounded by a post-read byte cap (SOCIAVAULT_MAX_BYTES, default 10MB) and a request timeout (SOCIAVAULT_TIMEOUT_MS, default 30s). The byte cap is checked after the body is buffered, so a fast, very large response from the upstream could allocate past the cap before the guard fires. Acceptable for a single trusted first-party vendor (api.sociavault.com); revisit with a streaming chunk-counted reader if this server is ever pointed at additional or untrusted endpoints.