linkedin-relay-mcp 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/skills/linkedin-relay/SKILL.md +205 -0
- package/LICENSE +21 -0
- package/README.md +98 -0
- package/dist/cli.js +2748 -0
- package/dist/cli.js.map +1 -0
- package/dist/index.js +700 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp-shim.js +2073 -0
- package/dist/mcp-shim.js.map +1 -0
- package/package.json +74 -0
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: linkedin-relay
|
|
3
|
+
description: Research LinkedIn from the user's own account — search people/companies/jobs, read profiles, read the chronological feed. Use when finding or evaluating people, companies or roles on LinkedIn, or reading what the user's network is posting. Not for posting, messaging, or connection requests — those are CLI-only and require the human.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# linkedin-relay
|
|
7
|
+
|
|
8
|
+
**"Research LinkedIn, not browse LinkedIn."** A CLI (`lnrelay`) + this read-only MCP surface, running
|
|
9
|
+
on the user's own logged-in session against LinkedIn's private Voyager API. No paid API, no browser
|
|
10
|
+
in the request path.
|
|
11
|
+
|
|
12
|
+
## Three things to know before you call anything
|
|
13
|
+
|
|
14
|
+
1. **Every call spends a budget that cannot be topped up.** Caps are deliberately low (30 profile
|
|
15
|
+
reads a day, 25 searches, 250 requests total) because LinkedIn restricts accounts for *read*
|
|
16
|
+
velocity alone — several documented restrictions involved no automation and no writes, just fast
|
|
17
|
+
browsing. Check `meta.budget.remaining`; when it's low, tell the user and stop rather than
|
|
18
|
+
spending the rest.
|
|
19
|
+
|
|
20
|
+
2. **An empty result is not the same as a failed fetch, and you must tell them apart.** Read
|
|
21
|
+
`meta.state` and the counts on every collection. Getting this wrong means telling the user
|
|
22
|
+
"there's nothing there" when the truth is "we failed to read it" — the single most damaging thing
|
|
23
|
+
this tool can do.
|
|
24
|
+
|
|
25
|
+
3. **Nothing is ever retried.** If a call fails with `RATE_LIMITED`, `REQUEST_DENIED`,
|
|
26
|
+
`CHALLENGE_DETECTED` or `COOLDOWN_ACTIVE`, a cross-process cooldown has opened and every
|
|
27
|
+
subsequent call will refuse until it lifts. **Do not loop.** Report it to the user and stop.
|
|
28
|
+
|
|
29
|
+
## The funnel
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
search cheap — cast wide, rank on the returned headline/location
|
|
33
|
+
↓ pick 2-3 finalists from the search rows alone, not by reading each one
|
|
34
|
+
profile mid — deep-read ONLY the finalists
|
|
35
|
+
feed mid — what the user's network is posting right now
|
|
36
|
+
↓ feed rows carry likes/comments counts — rank on those before reading a thread
|
|
37
|
+
post exp — a post's comment thread
|
|
38
|
+
reactions mid — who engaged with a post
|
|
39
|
+
whoami cheap — who we are authenticated as
|
|
40
|
+
risk / budget free — check standing BEFORE spending
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Search rows already carry name, headline, location and URL. **Rank on those.** Calling `profile` on
|
|
44
|
+
every search result is how a day's budget disappears in one request.
|
|
45
|
+
|
|
46
|
+
## Commands
|
|
47
|
+
|
|
48
|
+
### `search` — cheap. The net.
|
|
49
|
+
```
|
|
50
|
+
search kind:people|companies|jobs query:"<terms>" [limit:1-25]
|
|
51
|
+
```
|
|
52
|
+
Returns `{items, meta}`. Each item: `name`, `headline`, `location`, `url`, `urn`.
|
|
53
|
+
|
|
54
|
+
`meta.claimedCount` is LinkedIn's total for the query (often millions) — it is **not** how many you
|
|
55
|
+
got. `meta.state` is always `unknown` here: this is one page of many and we never claim exhaustion.
|
|
56
|
+
|
|
57
|
+
Out-of-network people come back as `name: "LinkedIn Member"` with a `/headless` URL. That is real
|
|
58
|
+
LinkedIn behaviour, not a bug — LinkedIn will not name them to this account. Say so rather than
|
|
59
|
+
presenting it as a data problem.
|
|
60
|
+
|
|
61
|
+
### `profile` — mid. Read only the finalists.
|
|
62
|
+
```
|
|
63
|
+
profile id:"<public-id|urn|linkedin.com/in/… URL>"
|
|
64
|
+
```
|
|
65
|
+
Returns `headline`, `location`, `title`, `company`, `school`, `urn`.
|
|
66
|
+
|
|
67
|
+
**Known limit: no name.** None of LinkedIn's profile projections returns first/last name, so a
|
|
68
|
+
looked-up profile has a headline but no name attached. You supplied the identifier, so use that.
|
|
69
|
+
Don't tell the user the profile is empty — it isn't.
|
|
70
|
+
|
|
71
|
+
### `feed` — mid. What the network is posting.
|
|
72
|
+
```
|
|
73
|
+
feed [limit:1-20]
|
|
74
|
+
```
|
|
75
|
+
Returns posts with `author`, `posted`, `text`, `url`, plus `likes`, `comments` and `threadUrn`.
|
|
76
|
+
Promoted posts are dropped and counted in `meta.excludedCount`, so `returnedCount` being lower than
|
|
77
|
+
`limit` is usually ads, not failure.
|
|
78
|
+
|
|
79
|
+
**Use the engagement counts to decide what to read.** A post with 601 comments and one with 3 cost
|
|
80
|
+
the same to fetch but are worth very different amounts. `threadUrn` is what `post` and `reactions`
|
|
81
|
+
take — pass it straight through rather than reconstructing it.
|
|
82
|
+
|
|
83
|
+
### `post` — expensive. The full read.
|
|
84
|
+
```
|
|
85
|
+
post urn:"<activity-urn | feed-update URL>" [limit:1-100]
|
|
86
|
+
```
|
|
87
|
+
The comment thread on a post. Accepts a bare `urn:li:activity:…`, a
|
|
88
|
+
`urn:li:ugcPost:…`, or a `linkedin.com/feed/update/…` URL — no prior lookup needed.
|
|
89
|
+
|
|
90
|
+
Returns comments with `author`, `headline`, `text`, `postedAt`, `url`. `meta.state` is `unknown`:
|
|
91
|
+
this is the first page and pagination is not followed yet, so **never report a comment count as
|
|
92
|
+
complete**. Nested replies are not supported — a comment with replies does not carry them.
|
|
93
|
+
|
|
94
|
+
Read only the finalists. Feed and search rows already tell you how many comments a post has; use
|
|
95
|
+
that to decide whether the thread is worth a call.
|
|
96
|
+
|
|
97
|
+
### `reactions` — medium. Who engaged.
|
|
98
|
+
```
|
|
99
|
+
reactions urn:"<activity-urn | feed-update URL>" [limit:1-100]
|
|
100
|
+
```
|
|
101
|
+
Who reacted and with which reaction type. Returns `name`, `headline`, `reaction`, `url`. Useful for
|
|
102
|
+
mapping who is paying attention to a topic — often more informative than the comments.
|
|
103
|
+
|
|
104
|
+
Same pagination caveat: `meta.state` is `unknown`.
|
|
105
|
+
|
|
106
|
+
### `whoami` — cheap. Who we are.
|
|
107
|
+
Confirms the session works and which account it is. Good first call in a fresh session.
|
|
108
|
+
|
|
109
|
+
### `local` — free. The default path after a research session.
|
|
110
|
+
```
|
|
111
|
+
local query:"<terms>" [source:connections,my-posts,third-party] [since:YYYY-MM-DD] [limit:N]
|
|
112
|
+
```
|
|
113
|
+
Offline search over whatever has been retained. **Costs nothing and spends no budget**, so prefer it
|
|
114
|
+
before reaching for a live command — if the answer is already cached, use it.
|
|
115
|
+
|
|
116
|
+
The cache only fills when a live read is run with `--retain` (CLI). If `meta.cachedTotal` is 0, the
|
|
117
|
+
cache is empty — that is not the same as LinkedIn having nothing, and the response says so.
|
|
118
|
+
|
|
119
|
+
### `connections` / `my-posts` — free. Cache-backed.
|
|
120
|
+
```
|
|
121
|
+
connections [query] [limit:N]
|
|
122
|
+
my-posts [query] [limit:N]
|
|
123
|
+
```
|
|
124
|
+
The user's own graph and posts, read from the local cache. **Free — no network call.** If they come
|
|
125
|
+
back empty, the cache has not been filled: tell the user to run `lnrelay sync connections` (or
|
|
126
|
+
`sync my-posts`) rather than reporting that they have none.
|
|
127
|
+
|
|
128
|
+
### `sync` — CLI-only. Fills the cache.
|
|
129
|
+
```
|
|
130
|
+
lnrelay sync my-posts | lnrelay sync connections [--limit N] [--force]
|
|
131
|
+
```
|
|
132
|
+
Not on this surface — the user runs it. Worth knowing it exists, because after a sync the `local`
|
|
133
|
+
tool can answer questions about their own posts and connections for free.
|
|
134
|
+
|
|
135
|
+
Connections refuse to re-sync more than once a week without `--force`: it is the most expensive read
|
|
136
|
+
in the tool and connections change slowly. Removals are only applied when the snapshot is complete —
|
|
137
|
+
if LinkedIn claims more connections than were retrieved, none are reported as removed, because they
|
|
138
|
+
were never looked at.
|
|
139
|
+
|
|
140
|
+
### `cache-status` — free.
|
|
141
|
+
What is cached per source, sync checkpoints, and the retention policy. Third-party records expire 30
|
|
142
|
+
days after capture: the body is deleted and an identity stub remains, so a re-fetch is a visible
|
|
143
|
+
choice rather than a silent budget charge. Owner data never expires.
|
|
144
|
+
|
|
145
|
+
### `risk` / `budget` — free, no network.
|
|
146
|
+
`risk` reports the circuit breaker. **Call it before a research session** rather than discovering a
|
|
147
|
+
lockout one wasted call at a time. `budget` reports spend per class with each cap's provenance.
|
|
148
|
+
|
|
149
|
+
### `doctor` — free with offline.
|
|
150
|
+
Diagnoses setup end to end. The first thing to run when anything behaves oddly.
|
|
151
|
+
|
|
152
|
+
## Reading `meta` — the part that matters
|
|
153
|
+
|
|
154
|
+
Every collection carries:
|
|
155
|
+
|
|
156
|
+
| field | meaning |
|
|
157
|
+
|---|---|
|
|
158
|
+
| `state: complete` | every reference resolved; an empty `items` here genuinely means none |
|
|
159
|
+
| `state: partial` | **some references failed to resolve** — the record is incomplete, not small |
|
|
160
|
+
| `state: unknown` | we stopped at the limit and cannot prove exhaustion (all searches) |
|
|
161
|
+
| `returnedCount` vs `claimedCount` | `claimed > 0` with `returned === 0` is a **failed fetch**, never "no results" |
|
|
162
|
+
| `excludedCount` | ads and UI chrome deliberately dropped |
|
|
163
|
+
| `unknownCount` / `unknownTypes` | **LinkedIn shipped a shape we don't recognise.** Data is still returned, but the parser is behind. Worth telling the user. |
|
|
164
|
+
| `unresolved` | URNs LinkedIn referenced but did not send |
|
|
165
|
+
|
|
166
|
+
If `unknownTypes` is non-empty, say so — it means LinkedIn changed something and the tool needs
|
|
167
|
+
re-capturing.
|
|
168
|
+
|
|
169
|
+
## Errors, and what to do
|
|
170
|
+
|
|
171
|
+
| code | what it means | what you do |
|
|
172
|
+
|---|---|---|
|
|
173
|
+
| `AUTH_FAILED` | session expired (usually just old cookies, not detection) | tell the user to run `lnrelay login` |
|
|
174
|
+
| `COOLDOWN_ACTIVE` | a previous call tripped the breaker | **stop.** Report when it lifts. |
|
|
175
|
+
| `RATE_LIMITED` / `REQUEST_DENIED` | LinkedIn throttled or blocked us | **stop.** Do not retry. |
|
|
176
|
+
| `CHALLENGE_DETECTED` | LinkedIn wants to see a human | stop; only the user can clear it, in a browser |
|
|
177
|
+
| `BUDGET_EXHAUSTED` | our own cap, not LinkedIn's | tell the user what's left and stop |
|
|
178
|
+
| `SCHEMA_DRIFT` | the endpoint changed shape or moved | report it; this needs a maintainer, not a retry |
|
|
179
|
+
| `NOT_IMPLEMENTED` | designed but not built yet | say so plainly |
|
|
180
|
+
|
|
181
|
+
**None of these is retryable.** A `retryAfterMs` is information for the human, not permission to
|
|
182
|
+
call again.
|
|
183
|
+
|
|
184
|
+
## What this tool will not do
|
|
185
|
+
|
|
186
|
+
Writes — posting, commenting, reacting — are **not on this surface at all**. They exist as CLI
|
|
187
|
+
commands (`lnrelay share`, `comment`, `react`) and go over LinkedIn's own official OAuth scope, not
|
|
188
|
+
the private API. Each stops at an interactive terminal, shows exactly what it will send, states the
|
|
189
|
+
ToS breach, and requires the user to type a token derived from the content.
|
|
190
|
+
|
|
191
|
+
**Without a terminal there is no write and no network call.** That is deliberate and there is no
|
|
192
|
+
flag that changes it: a flag an agent could set would not be confirming anything. If the user asks
|
|
193
|
+
you to post or comment, tell them the exact command to run themselves. Do not look for a way around
|
|
194
|
+
it, and do not offer one.
|
|
195
|
+
|
|
196
|
+
Connecting and messaging do not exist at all, in any surface. They are the actions where the
|
|
197
|
+
enforcement reports cluster, and an agent bug there is visible to a third party and unrecoverable.
|
|
198
|
+
|
|
199
|
+
Also absent by design: inbox reading, notifications, nested comment replies, and bulk sweeps.
|
|
200
|
+
|
|
201
|
+
## Honest risk
|
|
202
|
+
|
|
203
|
+
This uses LinkedIn's private API with the user's own session. It **breaches LinkedIn's User
|
|
204
|
+
Agreement §8.2** and the account can be restricted or permanently banned. The tool never claims
|
|
205
|
+
otherwise, and neither should you. If the user seems unaware, say it once, plainly.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Tamás Gábor
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# linkedin-relay
|
|
2
|
+
|
|
3
|
+
Deep research over LinkedIn from your own account — a TypeScript CLI (`lnrelay`), a read-only MCP
|
|
4
|
+
server, and a Claude Code skill. No paid API.
|
|
5
|
+
|
|
6
|
+
Sibling to [`x-relay`](../x-relay), [`github-relay`](../github-relay) and
|
|
7
|
+
[`youtube-context`](../youtube-context); same stack, same shape, same philosophy.
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm i -g linkedin-relay-mcp
|
|
11
|
+
lnrelay login # mint a session from your own Chrome
|
|
12
|
+
lnrelay search people "rust developer" # ranked rows: name, headline, location, url
|
|
13
|
+
lnrelay feed --compact # your feed, with engagement counts
|
|
14
|
+
lnrelay post <activity-urn> # a post's comment thread
|
|
15
|
+
lnrelay sync connections
|
|
16
|
+
lnrelay local "rust" # then search it offline, free
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## As an MCP server
|
|
20
|
+
|
|
21
|
+
Thirteen read-only tools, so an agent does the reading. Writes are not on that surface at any price.
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
claude mcp add linkedin-relay -s user -- bun "$(npm root -g)/linkedin-relay-mcp/dist/mcp-shim.js"
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Commands
|
|
28
|
+
|
|
29
|
+
| | |
|
|
30
|
+
|---|---|
|
|
31
|
+
| `search` · `profile` · `feed` | the research surface — people, companies, jobs |
|
|
32
|
+
| `post` · `reactions` | a post's comment thread, and who engaged |
|
|
33
|
+
| `sync` · `local` · `connections` · `my-posts` | fill a local cache, then query it for free |
|
|
34
|
+
| `whoami` · `doctor` · `risk` · `budget` · `cache-status` | session, standing and spend |
|
|
35
|
+
| `share` · `comment` · `react` | writes, over LinkedIn's official OAuth scope |
|
|
36
|
+
| `purge` | delete cached data |
|
|
37
|
+
|
|
38
|
+
Every command prints a JSON envelope on stdout. `--compact` and `--fields a,b` trim the output;
|
|
39
|
+
`--raw` keeps the original Voyager node for when a shape has drifted.
|
|
40
|
+
|
|
41
|
+
## Design in one screen
|
|
42
|
+
|
|
43
|
+
- **Browserless raw HTTP** to LinkedIn's Voyager API. A real browser mints cookies once, via CDP, and
|
|
44
|
+
is never in the hot path.
|
|
45
|
+
- **Zero automatic retry.** A 429 is a warning shot, not a suggestion to wait and try again.
|
|
46
|
+
Cooldowns are a *file*, so the breaker survives across processes.
|
|
47
|
+
- **Reads are paced as conservatively as writes** — restrictions get triggered by fast browsing with
|
|
48
|
+
no automation involved at all.
|
|
49
|
+
- **Budget as a type.** The client cannot be called without a `Permit` whose only producer is the
|
|
50
|
+
ledger. An unaccounted network call is a compile error.
|
|
51
|
+
- **Parse by exclusion, never by an accept-list** — and report unknown types in the envelope. A scar
|
|
52
|
+
carried from `x-relay`, where an accept-list silently dropped every reply in every thread and 34 of
|
|
53
|
+
77 posts per feed page while still returning `ok: true`.
|
|
54
|
+
- **Empty is never confused with failed.** Every collection reports `state`, `returnedCount` and
|
|
55
|
+
`claimedCount`; a claimed-but-empty response is an error, not "no results".
|
|
56
|
+
- **Third-party data is not cached by default.** When retained, a 30-day TTL swept on the read path;
|
|
57
|
+
on expiry the body dies and only an identity stub survives.
|
|
58
|
+
- **Writes need a human at a terminal.** No TTY, no write — and no network call on that path.
|
|
59
|
+
- **Single account by construction** — multi-account isn't disallowed, it's unrepresentable.
|
|
60
|
+
|
|
61
|
+
Full reasoning: **[docs/DESIGN.md](docs/DESIGN.md)** · Engine internals:
|
|
62
|
+
**[docs/ENGINE-RESEARCH.md](docs/ENGINE-RESEARCH.md)** · Build order: **[docs/PLAN.md](docs/PLAN.md)**
|
|
63
|
+
|
|
64
|
+
## Risk
|
|
65
|
+
|
|
66
|
+
LinkedIn does not offer individual developers a sanctioned read API, so this uses their private
|
|
67
|
+
Voyager surface with your own session. That is against LinkedIn's User Agreement, and any account it
|
|
68
|
+
touches can be restricted. Most of the design above exists to keep that risk low — conservative
|
|
69
|
+
pacing, no retries, a breaker that stops on the first signal — but it cannot be eliminated. Use an
|
|
70
|
+
account you would not mind losing.
|
|
71
|
+
|
|
72
|
+
`lnrelay risk` reports current standing; `lnrelay budget` reports what has been spent.
|
|
73
|
+
|
|
74
|
+
## Non-goals
|
|
75
|
+
|
|
76
|
+
Mass lead harvesting · multi-account operation or farms · proxy rotation · CAPTCHA solving ·
|
|
77
|
+
anti-detection tooling · reselling or sharing scraped data · outreach automation · anything that
|
|
78
|
+
touches another person's session.
|
|
79
|
+
|
|
80
|
+
## How this was built
|
|
81
|
+
|
|
82
|
+
Five parallel research lanes fed a three-model design panel — GPT-5.6-Sol, Grok-4.5 and Fable 5 —
|
|
83
|
+
who each wrote an independent proposal, then read and attacked each other's. All three changed
|
|
84
|
+
position under argument. The convergence and the full disagreement record are in
|
|
85
|
+
[docs/DESIGN.md](docs/DESIGN.md); the raw proposals are in `.orchestrate/panel/` and the research in
|
|
86
|
+
[docs/research/](docs/research/).
|
|
87
|
+
|
|
88
|
+
## Development
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
bun run check # typecheck + lint + 273 tests
|
|
92
|
+
bun run build
|
|
93
|
+
bun run dev -- <command>
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## License
|
|
97
|
+
|
|
98
|
+
MIT
|