Private LinkedIn Analytics MCP

1. 1

   Get a token

   Tokens map to exactly one LinkedIn profile and start with lnki_. Signing up issues one for you. To mint one by hand instead, use the admin API, authenticating with the Supabase service role key:

   $ curl -s -X POST https://www.getlinkintel.com/api/mcp/tokens     -H "Authorization: Bearer $SUPABASE_SERVICE_ROLE_KEY"     -H "Content-Type: application/json"     -d '{"label":"hermes"}'

   The response carries the token once. Only a hash is stored, so it cannot be shown again. Put it in a password manager now.

   {
     "token": "lnki_...",
     "label": "hermes",
     "profile_id": "...",
     "note": "Store this now. Only a hash is kept, so it cannot be shown again."
   }

   See Managing tokens for listing and revoking. There is also a CLI, if you have the repository checked out:

   $ pnpm --filter @linkintel/private-linkedin-mcp token:new --label="hermes"

2. 2

   Add the server

   For Claude Code:

   $ claude mcp add --transport http linkintel https://www.getlinkintel.com/api/mcp     --header "Authorization: Bearer $LINKINTEL_TOKEN"
   
   $ claude mcp list | grep linkintel   # expect: Connected

   For Claude Desktop and other clients that read a JSON config:

   {
     "mcpServers": {
       "linkintel": {
         "type": "http",
         "url": "https://www.getlinkintel.com/api/mcp",
         "headers": { "Authorization": "Bearer lnki_..." }
       }
     }
   }

   Prefer an environment variable over pasting the token into a config file that may end up in a backup or a screen share.

3. 3

   Confirm it works

   Ask the agent to call get_data_status. A healthy response looks like this:

   {
     "connected": true,
     "connection_status": "active",
     "data": { "total_days_stored": 90, "status": "fresh", "days_stale": 0 },
     "api_budget_today": { "used": 0, "limit": 75, "remaining": 75 }
   }

   To check without an agent, the endpoint speaks plain JSON-RPC over POST:

   $ curl -s -X POST https://www.getlinkintel.com/api/mcp     -H "Authorization: Bearer $LINKINTEL_TOKEN"     -H "Content-Type: application/json"     -H "Accept: application/json, text/event-stream"     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The block also reports days_stale, how much of the requested window actually has rows, and a plain-language warning when something is off.

Tools degrade rather than fail

Period members_reached needs a live LinkedIn call, because unique reach is only correct as a single official TOTAL window and can never be summed from daily figures. When that call is unavailable, the tool still returns every stored metric and sets reach to null with a reach_unavailable note. A null never becomes a zero, and a missing value is never compared against a real one to manufacture a delta.

"reach_unavailable": "LinkedIn safety budget reached (75 member requests today)...",
"metrics": {
  "impressions":     { "value": 10640, "previous": 9701, "delta": 939,  "percent_change": 9.7 },
  "members_reached": { "value": null,  "previous": null, "delta": null, "percent_change": null }
}

The logic lives in exactly one place, a scheduled Supabase edge function. Three callers invoke that same function, so there is no second copy to drift out of step.

As a client you only ever need sync_now. The nightly job keeps things current on its own, and the CLI is for whoever runs the server.

Backfills are resumable

• Per-day windows are fetched newest first, so an interrupted backfill leaves the recent days complete.
• Days that already hold a value are skipped, so re-running only pays for what is still missing.
• If the budget runs out mid-run, everything already fetched is saved and the tool returns status: "partial". Nothing is thrown away.
• Rows where nothing was measured are never written, since their nulls would sum to zero and read as a genuine day of no activity.

Safety cap

75 / UTC day

LinkedIn limit

100 / member / day

Headroom

25 requests

3-day sync

~13 requests

Cost is asymmetric, and this drives the whole backfill design:

Because a 90-day pull of the core metrics costs only seven requests, long backfills are cheap for everything that matters. Windows longer than seven days skip the daily MEMBERS_REACHED series deliberately: it is non-additive and is never summed into a period total, so it is a diagnostic not worth one request per day.

What repeated use actually costs

Most tools read only from storage and are free to call as often as you like. The two that need a live answer are cached, so asking the same question twice in a day costs nothing the second time.

A period’s unique reach cannot change once the window has closed, so it is cached until the date rolls over. Post metrics keep accruing, so they use a one-hour clock instead: a post published minutes ago is never reported as an hour stale. Responses carry reach_from_cache and from_cache so you can see which happened.

• Only a SHA-256 hash is stored. A database leak yields no working credentials, and the raw token exists exactly once, at the moment it is issued.
• Unknown, malformed and revoked tokens all return the same 401. Nothing distinguishes them, so the endpoint cannot be used to discover which tokens are real.
• Revocation applies on the very next request. There is no cache to wait out.
• Every use updates a last-seen timestamp, so a token that is no longer in use is easy to spot and retire.
• Tokens are not passwords and grant no access to your LinkedIn account. They only read analytics LinkedIn has already published to the profile owner.

Managing tokens

All three operations live at https://www.getlinkintel.com/api/mcp/tokens and take the Supabase service role key as a bearer. That is the right privilege level rather than a new one: anyone holding that key can already write to the tokens table directly, so this endpoint is convenience, not an escalation.

profile_id is optional while exactly one profile exists. Add a second and it becomes required, so a token can never silently land on the wrong profile.

$ curl -s https://www.getlinkintel.com/api/mcp/tokens     -H "Authorization: Bearer $SUPABASE_SERVICE_ROLE_KEY"

$ curl -s -X DELETE https://www.getlinkintel.com/api/mcp/tokens     -H "Authorization: Bearer $SUPABASE_SERVICE_ROLE_KEY"     -H "Content-Type: application/json"     -d '{"label":"hermes"}'

• LinkedIn reports roughly a one-day lag, and says aggregate reshares, reactions and comments can differ from its own UI.
• Period members_reached is fetched as a single official TOTAL window at tool time. Daily reach windows are kept only as a non-additive diagnostic and are never summed into period reach.
• Days backfilled in a window longer than seven days have no daily members_reached value by design. Period reach is unaffected.
• FOLLOWER_GAINED_FROM_CONTENT and PROFILE_VIEW_FROM_CONTENT currently return LinkedIn 500s. They are reported as non-blocking warnings and probed weekly, not on every sync.
• Per-post calls accept normal activity URLs and raw ugcPost or share URNs. Activity IDs are tried as ugcPost first and share on a 404. Posts are never enumerated or scraped.
• There is no official way to enumerate historical post URNs, which is why log_post exists: the content corpus is built from posts an agent explicitly registers.