Skip to main content
Glama

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

Available Tools

18 tools
linkup-credits-balanceLinkup credit balanceA
Read-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)A
Read-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 fetchA
Read-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)A
Read-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)A
Read-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 guideA
Read-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)B
Read-onlyIdempotent

List extract tasks (GET /v1/extract). Free. Closed beta.

Inputs: page, sort_by, page_size, sort_direction.

linkup-list-researchLinkup research tasks (list)A
Read-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)A
Read-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)A
Read-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-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)A
Read-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)A
Read-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)A
Read-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

    A3.9/5.0

    Scored across 18 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      11
      18 npm
      MIT
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -