linkup-mcp
This MCP server exposes Linkup's web API as tools for web search, page fetching, deep research, batch jobs, extraction, credits, and API guidance.
Search the web with selectable depth, date/domain filters, image/source/citation options, and search-results, sourced-answer, or structured output.
Fetch a single HTML/PDF page as markdown, optionally with JS rendering, pro mode, schema extraction, images, or raw content.
Create, wait for, poll, retrieve, and list deep research tasks with answer or structured outputs.
Create, inspect, and list mixed batch tasks for search, fetch, research, or extract work, including dry-run cost estimates and quota/status filters.
Check prepaid credit balance.
Use closed-beta extract, rewind search/fetch, and OpenAI-style responses endpoints when enabled.
Read a built-in Linkup API guide and an OpenAPI spec snapshot resource.
Apply response size caps/truncation hints and snake_case argument validation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@linkup-mcp search the web for the latest news on the EU AI Act"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: IB MCP Server
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, | 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-mcpClaude 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_KEYThe 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-mcpAny 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-mcpTest
.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 USDThe 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 mainTag that commit and push the tag:
git tag -a vX.Y.Z -m "linkup-mcp X.Y.Z" && git push origin vX.Y.ZThe 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.
Available Tools
18 toolslinkup-credits-balanceLinkup credit balanceARead-onlyIdempotent
Return the prepaid balance in USD (GET /v1/credits/balance). Free. Linkup credits eligible accounts back up to 20 USD a month; when the balance is used up the API answers 429. Extract tasks need a balance of at least 10 USD.
Inputs: no named parameters.
linkup-extractLinkup extract (closed beta, start task)A
Start an Extract task (POST /v1/extract) that turns a listing page into rows of data, delivered as an NDJSON file. CLOSED BETA: the API answers 403 unless Linkup has enabled it for the organisation. Variable price, typically 2 to 10 USD per completed task, shown as creditsUsed in the output; failed tasks are free; a balance of at least 10 USD is required. Asynchronous: poll with linkup-get-extract every 30 s, then download with linkup-extract-download. For one JSON object from one known page use linkup-fetch with schema instead.
Inputs: url (required), query (required), schema, verify_urls.
linkup-extract-downloadLinkup extract rows (download)ARead-onlyIdempotent
Download the NDJSON result of a completed extract task and return its rows as JSON. Free (the download link in the task output is a plain file URL, valid 24 hours).
Inputs: id (required), max_rows, max_chars.
linkup-fetchLinkup page fetchARead-only
Fetch one web page as clean markdown with Linkup (POST /v1/fetch, synchronous).
Price per call: standard 0.001 (no JS) or 0.005 (render_js); pro 0.005 or 0.01; a schema adds 0.001. Returns markdown and favicon always; data with a schema; images with extract_images; rawContent and contentType with include_raw_content. The endpoint is anonymous, reads this one URL only and follows no links. HTTP 400 is returned for binary files other than PDF, unreachable targets, oversize pages, instructions without schema, and failed structured extraction; such calls are not billed.
Inputs: url (required), mode, schema, max_chars, +4 more.
linkup-get-extractLinkup extract task (get)ARead-onlyIdempotent
Read one extract task (GET /v1/extract/{id}). Free. When completed, output holds creditsUsed, rowsReturned and resultUrl (an NDJSON download link valid for 24 hours); the rows are not in the response.
Inputs: id (required).
linkup-get-researchLinkup research result (poll once)ARead-onlyIdempotent
Read one research task (GET /v1/research/{id}). Free.
status is pending, processing, completed or failed. When completed, output holds the answer and sources (sourcedAnswer) or the JSON object (structured); when failed, error holds the reason. Poll at 2 s backing off to 10 s and never faster than once per second, or use linkup-wait-research, which does that for you.
Inputs: id (required), max_chars.
linkup-guideLinkup API guideARead-onlyIdempotent
Explain the Linkup API: endpoints, parameters, prices, latencies, limits, polling rules and best practices, condensed from Linkup's documentation (read 2026-11-13). Free, no network.
Inputs: topic.
linkup-list-extractLinkup extract tasks (list)BRead-onlyIdempotent
List extract tasks (GET /v1/extract). Free. Closed beta.
Inputs: page, sort_by, page_size, sort_direction.
linkup-list-researchLinkup research tasks (list)ARead-onlyIdempotent
List the organisation's research tasks (GET /v1/research). Free.
Returns data (tasks, each with id, status, input, error, createdAt, updatedAt and an output_preview, or the full output with include_output) and metadata (page, pageSize, total, totalPages). Results are kept for a bounded period; store what you need.
Inputs: page, sort_by, max_chars, page_size, +2 more.
linkup-researchLinkup deep research (start task)A
Start an autonomous research task with Linkup (POST /v1/research). Asynchronous: returns at once with id and status "pending"; the agent then plans, searches many sources in parallel, verifies and synthesises, in 2 to 20 minutes. Collect the result with linkup-wait-research (polls for you) or linkup-get-research.
Price per task by reasoning_depth: S 0.25 USD (2 to 5 min), M 0.50 (3 to 7 min),
L 1.50 (5 to 10 min, the default), XL 2.50 (10 to 20 min). Failed tasks are not billed.
Do not create a second task to "retry" a slow one; wait on the id you have.
Use it for questions a single search cannot resolve: verified answers with an audit trail
of citations, a focused investigation of one subject, or a broad report by theme. For a
quick fact use linkup-search. Set mode explicitly for predictable latency, cost and
shape. Phrase the question precisely: angles to cover, leads to pursue, facts to verify,
entities to compare, constraints, and the structure you expect back. Put dates in
from_date/to_date, give a few trusted include_domains when they exist.
Inputs: query (required), mode, to_date, from_date, +5 more.
linkup-responsesLinkup responses (OpenAI-style)ARead-only
Generate a web-grounded answer in the OpenAI Responses format (POST /v1/responses). This is the endpoint behind using Linkup as an OpenAI-compatible base URL. Returns output_text and output messages with url_citation annotations. Its price is not published on the pricing page (read 2026-11-13); check linkup-credits-balance before and after if it matters. For most uses linkup-search with sourcedAnswer is the simpler call.
Inputs: input (required), model, max_chars, text_format, +1 more.
linkup-rewind-fetchLinkup rewind fetch (beta)ARead-only
Return a page as it was at the end of a given UTC day (POST /v1/rewind/fetch). CLOSED BETA: 403 unless enabled; 404 when no revision is visible that day; 422 when the day is not available.
Inputs: url (required), as_of (required), max_chars.
linkup-rewind-searchLinkup rewind search (beta)ARead-only
Search the web as it was at the end of a given UTC day (POST /v1/rewind/search). CLOSED BETA: 403 unless enabled for the organisation. Returns results with content, name, url, validFrom and validTo (the first day the revision was no longer visible, null if current).
Inputs: as_of (required), query (required), max_chars.
linkup-searchLinkup web searchARead-only
Search the web with Linkup (POST /v1/search, synchronous).
Cost per call: flash, fast or standard 0.005 USD (searchResults) or 0.006 (sourcedAnswer, structured); deep 0.05 or 0.055. Rate limit 10 requests per second per organisation. A query without results returns HTTP 400 and is not billed. LinkedIn profile, company and post pages can only be read through this endpoint (give the exact URL in the query with standard or deep), not through linkup-fetch.
Inputs: query (required), depth, to_date, from_date, +9 more.
linkup-tasks-createLinkup batch tasks (create)A
Create a batch of asynchronous tasks (POST /v1/tasks). Each task is billed exactly like the direct call: search 0.005 to 0.055, fetch 0.001 to 0.011, research 0.25 to 2.50 (100 research tasks at the default depth L cost 150 USD), extract variable (2 to 10 typical). There is no batch discount; Tasks is for bulk, long-running or mixed work, not for single calls.
Returns the task envelopes (id, type, status pending, input, output null). Then poll with linkup-tasks-list (bulk, every 5 s for research, 1 to 2 s for search and fetch) or linkup-tasks-get (one task). A failing task does not fail the batch and is not billed. The organisation has a concurrency quota (see quota in linkup-tasks-list); above it the API answers 429. Results are kept for a bounded period: store them when they complete.
Inputs: tasks (required), dry_run.
linkup-tasks-getLinkup task (get)ARead-onlyIdempotent
Read one task of any type (GET /v1/tasks/{id}). Free. status: pending, processing, completed, failed. output has the same shape as the matching synchronous endpoint; for extract tasks it holds resultUrl (download with linkup-extract-download).
Inputs: id (required), max_chars.
linkup-tasks-listLinkup tasks (list)ARead-onlyIdempotent
List the organisation's tasks of all types (GET /v1/tasks). Free. Returns data (task envelopes with an output_preview, or full outputs with include_output), metadata (page, pageSize, total, totalPages) and quota (inFlight: tasks pending or processing now; limit: maximum concurrent tasks allowed). Prefer this bulk poll over many linkup-tasks-get calls; the poll cap is 1 request per second.
Inputs: page, type, status, sort_by, +4 more.
linkup-wait-researchLinkup research result (wait)ARead-onlyIdempotent
Wait for a research task and return it when it is completed or failed (GET /v1/research/{id} in a loop).
Polls at Linkup's recommended cadence: 2 s, doubling up to 10 s, never above 1 request per second, and reports progress to the client. If max_wait_seconds elapses first, the task is returned with its current status (pending or processing) and done=false: call this tool again with the same id. Free; the task itself was billed when created.
Inputs: id (required), max_chars, max_wait_seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Most tools map to a distinct endpoint and resource (search, fetch, research, tasks, extract, rewind, credits), and descriptions explicitly steer between them (e.g. 'for a quick fact use linkup-search'). Residual overlap exists between linkup-search/sourcedAnswer, linkup-responses and linkup-research, and between linkup-research and linkup-tasks-create with a research type, which could still cause misselection.
Names mix verb-first and resource-first ordering inconsistently: linkup-get-research / linkup-list-research / linkup-get-extract sit alongside linkup-tasks-get / linkup-tasks-list, and linkup-credits-balance is noun_noun. All are kebab-case and readable, but the same operation is spelled two different ways across resource families.
18 tools is on the heavy side, but the surface spans several genuinely distinct feature areas (search, fetch, async research, batch tasks, extract, rewind, responses, billing, guide), each needing its own create/read/list or download. A few—linkup-responses, linkup-guide, and the closed-beta rewind pair—are marginal additions rather than core.
The surface covers the main lifecycle well: create/poll/list/wait for research, bulk create/get/list for tasks, extract create/get/list/download, credits, and an offline guide. The notable gap is the absence of cancel/delete operations for research, task, or extract resources, which matters for long-running, billable async work.
Maintenance
Related MCP Connectors
Query, browse, and automate OmegaAI workspaces from any MCP client. Streamable HTTP with OAuth 2.0.
The world's public data, one API. License-cleared public data sources for agents, via MCP and REST.
A managed runtime for custom API integrations. Manage lines, endpoints, keys, logs and DLQ via MCP.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables MCP clients to run live web searches, fetch and navigate readable web pages, search images, capture PDF screenshots, and retrieve finance, weather, sports, and world-time data through a zero-configuration authenticated backend.1118 npmMIT
- FlicenseNot gradedqualityNot gradedmaintenanceEnables users to interact with Interactive Brokers' official Web API through MCP, supporting account management, reporting, and other brokerage operations via the Client Portal Gateway for retail authentication.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients to scrape web pages, extract structured data, search, crawl sites, generate schemas, schedule monitors, and inspect credits/history through hosted or local integrations.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients to perform AI-powered web scraping, extraction, search, crawling, schema generation, and scheduled monitor management through local or hosted integration.-