MCP server

Give an assistant one tool per Sourcevine API that takes a URL. Read-only, available locally or over hosted MCP, and reports what each call cost.

@sourcevine/mcp gives an assistant that speaks the Model Context Protocol one tool per named API that takes a URL: stats, profile, posts and comments on each platform, plus YouTube transcripts (16 tools). Search, trending and other query-based APIs are HTTP-only for now. It can run locally over stdio, or through the hosted Streamable HTTP endpoint at https://mcp.sourcevine.io/mcp.

It is read-only. Nothing in the tool surface posts, follows, messages or changes anything on any platform, and every tool is annotated readOnlyHint so a client can skip a confirmation it would otherwise be right to show.

Install

Create a key at app.sourcevine.io/keys. For Claude Code:

claude mcp add sourcevine --env SOURCEVINE_API_KEY=sv_live_... -- npx -y @sourcevine/mcp

For Codex:

codex mcp add sourcevine --env SOURCEVINE_API_KEY=sv_live_... -- npx -y @sourcevine/mcp

Replace the placeholder locally with your key. Both commands configure the local stdio server; Node.js 20.10 or later is required. Start a new client session to load the tools if necessary.

Or, for anything that reads a JSON config:

{
  "mcpServers": {
    "sourcevine": {
      "command": "npx",
      "args": ["-y", "@sourcevine/mcp"],
      "env": { "SOURCEVINE_API_KEY": "sv_live_..." }
    }
  }
}

Hosted endpoint

If your MCP client supports remote Streamable HTTP, point it at:

{
  "mcpServers": {
    "sourcevine": {
      "url": "https://mcp.sourcevine.io/mcp",
      "headers": { "Authorization": "Bearer sv_live_..." }
    }
  }
}

The hosted endpoint is stateless. Your key arrives as a bearer token, is used for that request, and is forwarded to the Sourcevine API. The local stdio server stores the key in your client configuration and sends it directly to the Sourcevine API. Either way, Sourcevine receives the key to authenticate API requests.

Tools

One per API, named after it, so an assistant picks an endpoint by name rather than resolving a URL first and hoping.

Examples of tools available for public post reporting:

Each tool’s description includes its live credit price. See the API catalog for current prices and response fields. Not-found and private lookups are charged at the operation’s price.

The list is generated from the same catalog that defines the routes, so a tool cannot exist without an API behind it.

Every tool takes a url. List tools also take cursor and limit.

What comes back

The per-platform object documented at sourcevine.io/apis, plus what the call cost:

{
  "data": {
    "username": "atlas.makes",
    "nickname": "Atlas Makes",
    "followerCount": 482300,
    "videoCount": 618,
    "heartCount": 9140000,
    "fetchedAt": "2026-08-28T09:41:44Z"
  },
  "creditsCharged": 1
}

Successful and unavailable results include creditsCharged, or null when the charge was not reported. Tool errors can return plain text without a charge field. Treat missing charges as unknown; do not replace them with zero.

Task-specific skills

The free Sourcevine agent skills add focused workflows to these tools: Campaign Report, Competitor Content Brief, and Audience Questions & Objections. Each sets a scope and credit budget, preserves source evidence, and produces files you can reuse. Install your skills after connecting MCP. Skill installation is free; API usage consumes credits.

Things to know

Unavailable is not an error. A private or deleted resource comes back as a normal result with available: false, charged at the tool’s price like any lookup:

{
  "available": false,
  "availability": { "status": "not_found", "reason": null },
  "creditsCharged": 1
}

Returning an error here would put an agent in a retry loop on a post that no longer exists.

Use a separate key. Give the server its own key on its own project, so you can see what the assistant spent and revoke it independently of everything else.

Set a balance alert before you find out you needed one.

No contact data. No bios, emails, phone numbers, postal addresses or private-account data or restricted content. That is enforced on the server by an allowlist, not by the package, so it holds however the tools are called. See the privacy boundary.

Source

sourcevine-mcp, MIT licence. npm test covers the tool surface, the billing defaults, and that the key never travels in a URL.

Last updated 5 October 2026