feedpik — CLI and MCP server

CLI and MCP server for Feedpik — the RSS reader where the ranking algorithm belongs to you.

Built for both humans and AI agents: every command returns a stable JSON envelope ({ok, data, error}), so an agent can drive your feed with scoped, auditable, rollbackable changes.

Personas. A persona is a complete reading space — its own sources, topic preferences, reading history, and ranking algorithm. Every command acts on the active persona; persona use <id> swaps the whole space.

Sign in

npx feedpik@latest login

This prints a short code and a URL. Approve it in a browser — any device, it does not have to be the machine running the CLI, which is what makes this work on a headless box. The key is saved to ~/.feedpik/config.json (mode 0600) and reused by both the CLI and the MCP server.

Read access is the default. Request write access only when you need it, and your browser shows exactly what is being granted before you approve:

npx feedpik@latest login --scopes feeds:read,recommendations:read,recommendations:write

feedpik logout forgets the key on this machine; revoke the key itself under Algorithm & Agents → Agents & Access.

A token from an environment variable still wins over the saved one, which is handy in CI:

export FEEDPIK_API_TOKEN=vrss_...
# optional, defaults to https://feedpik.com
export FEEDPIK_API_URL=https://feedpik.com

MCP server

If your agent speaks the Model Context Protocol — Claude Desktop, Claude Code, Cursor — skip the CLI and add the server instead. No shell required:

{
  "mcpServers": {
    "feedpik": {
      "command": "npx",
      "args": ["-y", "-p", "feedpik", "feedpik-mcp"]
    }
  }
}

-p feedpik names the package, feedpik-mcp the binary inside it — the server ships alongside the CLI so both share one login.

It exposes 18 tools: feedpik_get_profile, feedpik_update_profile, feedpik_list_candidates, feedpik_record_feedback, feedpik_get_policy, feedpik_update_policy, feedpik_rollback_policy, feedpik_list_personas, feedpik_switch_persona, feedpik_list_feeds, feedpik_add_feed, feedpik_remove_feed, feedpik_discover_sources, feedpik_list_packs, feedpik_install_pack, feedpik_whoami, plus feedpik_login_start / feedpik_login_complete for the same browser approval flow.

Usage

npx feedpik@latest --help

# who am I, and what can this key do?
npx feedpik@latest whoami

# ranked candidates with reasons
npx feedpik@latest candidates --limit 10

# what the reader wants, and never wants — the fastest lever on ranking, and
# the only one that does anything for an account with no subscriptions
npx feedpik@latest profile get
npx feedpik@latest profile set --interests "artificial intelligence,semiconductors" --blocked crypto
npx feedpik@latest profile set --sources Stratechery --authors "Ben Thompson"

# the signature move: tune the ranking policy as a NEW rollbackable version
npx feedpik@latest policy get
npx feedpik@latest policy set --file my-config.json --name "More AI infra, less crypto"
npx feedpik@latest policy versions
npx feedpik@latest policy rollback <versionId>

# teach the ranking
npx feedpik@latest feedback <articleId> liked

# personas — each is a whole reading space (sources + preferences + history + algorithm)
npx feedpik@latest persona list
npx feedpik@latest persona use <personaId>
npx feedpik@latest persona new "Market open"

# subscriptions & discovery (always the ACTIVE persona)
npx feedpik@latest feeds list
npx feedpik@latest feeds add https://example.com/feed.xml --folder Tech
npx feedpik@latest discover "ai infrastructure"

# source packs — merge their sources into the active persona
npx feedpik@latest packs list
npx feedpik@latest packs install <packId>

# community personas — arrive as a NEW persona, yours stays untouched
npx feedpik@latest personas browse
npx feedpik@latest personas get <packId>

# portability
npx feedpik@latest opml export --output backup.opml
npx feedpik@latest opml import feeds.opml

# the live agent skill document
npx feedpik@latest skill

Output contract

{ "ok": true, "data": {}, "error": null }
{ "ok": false, "data": null, "error": { "code": "UNAUTHORIZED", "message": "..." } }

Exit code 0 on success, 1 on error. skill and opml export print raw content instead of the envelope.

Scopes

Use the minimum scopes for the job: recommendations:read for candidates, recommendations:write for policy tuning/rollback, profile:write for interests and blocked topics, feeds:read/feeds:write for subscriptions, OPML, and packs.

profile:write is the one an agent setting up a new account needs. Each list in profile set REPLACES the stored one, so read it first and send the whole list. Topics and sources match as substrings; bylines match exactly.

Agent changes to the policy always create a new version with an audit trail — nothing is silently overwritten, and everything is one policy rollback away.