linkup-mcp
An MCP server for the whole Linkup web API, one tool per operation, with Linkup's own operational guidance (prices, latencies, limits, polling rules, best practices) in the tool descriptions and in a built-in guide. Stdio transport, Python, two dependencies.
Not affiliated with Linkup. Written against https://api.linkup.so/v1/openapi.json and the
documentation as read on 2026-11-13; the snapshot of the spec is shipped as a resource.
Why
Linkup's official server (linkup-mcp-server,
also hosted at https://mcp.linkup.so/mcp) exposes four tools: linkup-search (always a
sourced answer, no output type), linkup-research (output fixed to sourcedAnswer),
linkup-get-research and linkup-fetch (no pro mode, no schema extraction). It has no
research listing, no batch tasks, no credit balance, no extract, rewind or responses. This
server keeps those four tool names, gives them every documented parameter, and adds the rest.
Tools
| Tool | API | Billed per call (USD) |
|---|---|---|
| linkup-search | POST /search | 0.005 to 0.055 |
| linkup-fetch | POST /fetch | 0.001 to 0.011 |
| linkup-research | POST /research (create task) | 0.25 (S), 0.50 (M), 1.50 (L), 2.50 (XL) |
| linkup-wait-research | GET /research/{id}, polled 2 s doubling to 10 s, time-boxed, resumable | free |
| linkup-get-research | GET /research/{id} | free |
| linkup-list-research | GET /research | free |
| linkup-tasks-create | POST /tasks, 1 to 100 items, dry_run returns the cost estimate |
as the wrapped calls |
| linkup-tasks-get | GET /tasks/{id} | free |
| linkup-tasks-list | GET /tasks, with type and status filters and the concurrency quota | free |
| linkup-credits-balance | GET /credits/balance | free |
| linkup-extract, linkup-get-extract, linkup-list-extract, linkup-extract-download | /extract (closed beta: 403 unless enabled) | variable, 2 to 10 typical |
| linkup-rewind-search, linkup-rewind-fetch | /rewind (closed beta) | not published |
| linkup-responses | POST /responses (OpenAI Responses format) | not published |
| linkup-guide | documentation, no network | free |
Resources: linkup://guide (the full guide) and linkup://openapi.json (the spec snapshot).
Behaviour worth knowing:
- Research tasks are created once and polled.
linkup-wait-researchreturns aftermax_wait_seconds(default 600) withdone: falseif the task still runs and can be called again with the same id. It never re-creates a task. A network error, a timeout, an HTTP 429 or an HTTP 5xx during the wait does not end the wait. The tool polls again untilmax_wait_secondsand reportstransient_errorsandlast_error. - Every tool that returns results, tasks, lists or rows takes
max_charsand keeps its response within it. The response is compact JSON. The cap applies to the text that is sent. The order of cuts is: raw content and source snippets, then other long strings, then trailing sources, results and images, then the answer or markdown, then trailing items of other lists. A<list>_omittedcounter gives the number of dropped items._truncatedand_hintsay when a cut happened. A research answer comes back byte-identical to the API when the answer and the task envelope (usually less than 1,000 characters) fit in the cap. The two create calls (linkup-research,linkup-extract), the balance and the guide have no cap. They return no results. The create calls return the task envelope with your own input. - Tool parameters are snake_case. A call with an unknown parameter name (for example
outputType) fails with an error that names the valid parameters. No request is sent to Linkup. A snake_case key in an input object oflinkup-tasks-createfails in the same way. linkup-list-research,linkup-list-extractandlinkup-tasks-listreturn anoutput_previewper task;include_output: truereturns the full outputs.- Errors carry Linkup's status code, its error body, and a one-line hint (for example 429: rate limit or empty balance).
Install
With uv, from PyPI, no checkout needed:
uvx linkup-mcp
Claude Code, user scope. The key is stored in the env of the entry, not in its args.
read -rs keeps the key out of the shell history. The key is on the command line of the
claude process only while the command runs. The first command waits without a prompt.
Paste the key, then press Enter. Nothing is shown.
read -rs LINKUP_API_KEY
claude mcp add-json --scope user linkup '{"type":"stdio","command":"uvx","args":["linkup-mcp"],"env":{"LINKUP_API_KEY":"'"$LINKUP_API_KEY"'"}}'
unset LINKUP_API_KEY
The current main branch instead of the release: replace linkup-mcp in args with
--from, git+https://github.com/cybernagl/linkup-mcp, linkup-mcp, or run
uvx --from git+https://github.com/cybernagl/linkup-mcp linkup-mcp
Any other MCP client: run linkup-mcp (or python -m linkup_mcp) over stdio with
LINKUP_API_KEY in the environment.
Environment: LINKUP_API_KEY (required), LINKUP_BASE_URL (default
https://api.linkup.so/v1), LINKUP_TIMEOUT (seconds per HTTP request, default 180).
From a checkout:
git clone https://github.com/cybernagl/linkup-mcp && cd linkup-mcp
uv venv && uv pip install -e .
.venv/bin/linkup-mcp
Test
.venv/bin/python tests/test_wait.py # offline: wait loop, error mapping, size cap, argument checks, list summaries
.venv/bin/python tests/selftest.py # protocol checks, plus free live calls when LINKUP_API_KEY is set
.venv/bin/python tests/selftest.py --paid # adds two fast searches and two fetches, about 0.014 USD
The self-test never creates a research task (0.25 USD and up). GitHub Actions runs the offline tests and the protocol self-test on Python 3.11, 3.12 and 3.13 for every push.
Release
Releases reach PyPI through trusted publishing: GitHub Actions proves its identity to PyPI with an OIDC token, and PyPI mints a 15-minute upload token for this project. No API token is stored anywhere.
- Set the new version in
pyproject.tomland commit it to main - Tag that commit and push the tag:
git tag -a vX.Y.Z -m "linkup-mcp X.Y.Z" && git push origin vX.Y.Z - The Release workflow (
.github/workflows/release.yml) checks that the tag matches the version, runs the tests, builds wheel and sdist, and then waits in thepypienvironment for an approval on the Actions page. After the approval it uploads to PyPI
The publisher registered on PyPI is repository cybernagl/linkup-mcp, workflow
release.yml, environment pypi. The environment accepts v* tags only and requires a
reviewer. A run that fails before the upload can be re-run or re-tagged at the same version;
a version that reached PyPI cannot be replaced and needs a new version number.
Claude Code Notes
- Results above 50,000 characters (or
MAX_MCP_OUTPUT_TOKENS, default 25,000 tokens) are saved to a file by Claude Code and handed over as a path. The defaultmax_charscaps (40,000 for search, fetch and lists; 48,000 for a research or task result) keep results inline; raisemax_charswhen you want everything. MCP_TOOL_TIMEOUTdefaults to about 28 hours and stdio servers have no per-request timer, so long research waits are safe.
Updating the Guide
Prices, limits and wording come from Linkup's documentation
(https://docs.linkup.so/llms.txt). They live in src/linkup_mcp/server.py next to
DOCS_READ_DATE. When Linkup changes something, update the text and the date, and replace
src/linkup_mcp/openapi.json with a fresh download of the spec.
License
MIT.
Metadata
Release files for linkup-mcp 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| linkup_mcp-0.1.1.tar.gz | 45.6 kB | With provenance | Details for linkup_mcp-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| linkup_mcp-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for linkup_mcp-0.1.1-py3-none-any.whl |
Total release size: 82.7 kB
Release files / linkup_mcp-0.1.1.tar.gz
| Download URL | linkup_mcp-0.1.1.tar.gz |
|---|---|
| Size | 45.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d7ca4ee93016154c9d4263afc7d3955df1e13024b823042f1d2693e5542027de
|
|
BLAKE2b-256 checksum How to use checksums |
43d30cf51ef3c4b8f7d87cb1c0869ce46728460fc9907e824fe09521ff31e5fb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / linkup_mcp-0.1.1-py3-none-any.whl
| Download URL | linkup_mcp-0.1.1-py3-none-any.whl |
|---|---|
| Size | 37.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
800c6e6b6d7e6794b73dfea48fb270c65202fc95383d4acf193e9c1bbc25bdcf
|
|
BLAKE2b-256 checksum How to use checksums |
b5f2f91f096ee7fcbf090ad0389ff6c640596df4b62e9f59b72428cfd211ce0b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logSecurity for linkup-mcp 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for linkup_mcp-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.