Skip to main content

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-research returns after max_wait_seconds (default 600) with done: false if 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 until max_wait_seconds and reports transient_errors and last_error.
  • Every tool that returns results, tasks, lists or rows takes max_chars and 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>_omitted counter gives the number of dropped items. _truncated and _hint say 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 of linkup-tasks-create fails in the same way.
  • linkup-list-research, linkup-list-extract and linkup-tasks-list return an output_preview per task; include_output: true returns 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.

  1. Set the new version in pyproject.toml and commit it to main
  2. 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
  3. 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 the pypi environment 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 default max_chars caps (40,000 for search, fetch and lists; 48,000 for a research or task result) keep results inline; raise max_chars when you want everything.
  • MCP_TOOL_TIMEOUT defaults 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)

Source distribution for linkup-mcp 0.1.1
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)

Table of built distributions (wheels) for linkup-mcp 0.1.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page