Link Finder MCP

🇫🇷 Version française

An MCP server for the Link Finder API — find backlink opportunities, analyze competitors, discover similar domains with AI embeddings, and manage prospecting projects directly from Claude, ChatGPT, Cursor, or any MCP client.

Secrets are provided only through environment variables, and the server is host-agnostic: run it locally over stdio, or deploy it anywhere (Render or any VM) with a bearer-token-protected HTTP/SSE endpoint.

Features

All Link Finder API v2 endpoints are exposed as tools:

Plus a guided prompt backlink_workflow that runs the step-by-step interview and prospecting flow.

The server also follows the API's best practices: every search result is saved locally to a data/ folder and logged in data/searchHistory.json so agents can avoid duplicate, credit-wasting searches.

Related MCP server: PaidSync (Ads analysis & Management)

Requirements

• Python 3.10+

• A Link Finder API key — get it in your account at https://app.link-finder.net/account/ (Booster plan or higher; checkDomain and bulk need the API plan)

Installation

git clone https://github.com/<you>/link-finder-mcp.git
cd link-finder-mcp

python -m venv .venv && source .venv/bin/activate    # optional but recommended
pip install -r requirements.txt

Copy the example environment file and fill in your key:

cp .env.example .env
# then edit .env and set LINK_FINDER_API_KEY

No credentials in code. The API key is read only from LINK_FINDER_API_KEY and is never accepted as a tool argument, so it can't leak through the model context.

Configuration

All configuration is via environment variables:

Which transport?

• Local clients (Claude Desktop, Cursor, ...) → stdio.

• Hosted (Render or any VM) → http (Streamable HTTP). This is the recommended, proxy-friendly transport; the endpoint lives at /mcp.

• sse is the older transport (endpoint at /sse). It works, but long-lived SSE streams can be buffered or reset by PaaS proxies, which can stall the MCP initialization handshake. Prefer http unless your client only speaks SSE.

Connect it to your AI chat — pick your setup

There are two ways to use this server. Choose based on your chat app:

Rule of thumb: desktop app → A (local), web/cloud chat → B (hosted).

Running locally (stdio)

export PYTHONPATH=src
python -m link_finder_mcp.server

Or debug interactively with the MCP Inspector:

PYTHONPATH=src mcp dev src/link_finder_mcp/server.py

A. Use with Claude Desktop (local)

Edit your Claude config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "link-finder": {
      "command": "python",
      "args": ["-m", "link_finder_mcp.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/link-finder-mcp/src",
        "MCP_TRANSPORT": "stdio",
        "LINK_FINDER_API_KEY": "your_link_finder_api_key_here",
        "LINK_FINDER_DATA_DIR": "/absolute/path/to/link-finder-mcp/data"
      }
    }
  }
}

Restart Claude Desktop. You'll see the Link Finder tools under the tools (hammer) icon. Try:

"Check my Link Finder credits, then find French backlink opportunities for the keywords assurance auto;comparateur assurance with DR 20+ and 500+ traffic. Save the best ones to a new project called Assurance Q3."

Claude will chain get_account → keyword_search → create_project → add_favorite, then suggest similar_domains on the top matches.

Tip: in Claude Desktop you can also attach the backlink_workflow prompt (the "+" / prompts menu) to launch the full guided interview.

B. Use with ChatGPT (hosted)

ChatGPT supports remote MCP servers (Developer mode / custom connectors and the Responses API tools of type mcp). For that you need the server reachable over HTTPS with a bearer token — see Deploy on Render first.

Option A — ChatGPT Developer Mode / Connectors (UI)

1. Deploy the server (e.g. on Render) with MCP_TRANSPORT=http and a strong MCP_BEARER_TOKEN.

2. In ChatGPT: Settings → Connectors → Advanced → Developer mode, then Create a connector.

3. Set the server URL to your deployment's MCP endpoint, e.g. https://your-app.onrender.com/mcp.

4. Add an Authorization header: Bearer <your MCP_BEARER_TOKEN>.

5. Save, then enable the connector in a chat and ask it to find backlinks.

Option B — OpenAI Responses API (programmatic)

from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "mcp",
            "server_label": "link-finder",
            "server_url": "https://your-app.onrender.com/mcp",
            "headers": {"Authorization": "Bearer YOUR_MCP_BEARER_TOKEN"},
            "require_approval": "never",
        }
    ],
    input="Use Link Finder to find Spanish (language 2724) backlink "
          "opportunities for 'hosting wordpress' with TF 15+ and report a table.",
)

print(resp.output_text)

A. Use with Cursor (local)

Add to ~/.cursor/mcp.json (or the project .cursor/mcp.json):

{
  "mcpServers": {
    "link-finder": {
      "command": "python",
      "args": ["-m", "link_finder_mcp.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/link-finder-mcp/src",
        "LINK_FINDER_API_KEY": "your_link_finder_api_key_here"
      }
    }
  }
}

B. Use with any other AI chat / MCP client (hosted)

Most other clients (Claude on the web, n8n, custom apps, MCP SDKs, ...) connect to a remote MCP server the same way: a URL + a bearer token. After you deploy:

{
  "url": "https://your-app.onrender.com/mcp",
  "headers": { "Authorization": "Bearer YOUR_MCP_BEARER_TOKEN" }
}

• URL → your deployment + /mcp (Streamable HTTP). Use /sse only if your client speaks the legacy SSE transport.

• Token → the exact value you set in MCP_BEARER_TOKEN.

That's all any compliant MCP client needs. Once connected, just ask in plain language (e.g. "find backlink opportunities for my coffee blog in France") and the model will call the right tools.

Deploy on Render (or any VM)

The server is host-agnostic. In hosted mode it binds 0.0.0.0:$PORT and protects the MCP endpoints with a bearer token. The recommended hosted transport is Streamable HTTP (MCP_TRANSPORT=http), served at /mcp.

A ready-made render.yaml is included:

services:
  - type: web
    name: link-finder-mcp
    runtime: python
    buildCommand: pip install -r requirements.txt
    startCommand: python -m link_finder_mcp.server
    envVars:
      - key: PYTHONPATH
        value: src
      - key: MCP_TRANSPORT
        value: http
      - key: LINK_FINDER_API_KEY
        sync: false
      - key: MCP_BEARER_TOKEN
        sync: false

1. Push this repo to GitHub.

2. In Render: New → Blueprint, point it at the repo.

3. Set the two secret env vars (LINK_FINDER_API_KEY, MCP_BEARER_TOKEN) in the dashboard.

4. Deploy. Your MCP endpoint will be https://<service>.onrender.com/mcp.

The same works on any VM / PaaS — just set the env vars and run python -m link_finder_mcp.server. Set MCP_TRANSPORT=sse (endpoint /sse) only if your client requires the legacy SSE transport.

Point your client at the /mcp endpoint with the bearer token:

{
  "url": "https://your-app.onrender.com/mcp",
  "headers": { "Authorization": "Bearer YOUR_MCP_BEARER_TOKEN" }
}

Note on saved data: on ephemeral hosts (like Render's default disk) the data/ folder is not persistent. Mount a persistent disk, or set LINK_FINDER_DATA_DIR to a mounted path, if you want the search history to survive restarts. Local (stdio) usage persists normally.

Troubleshooting

• Failed to validate request: Received request before initialization was complete (repeating, on SSE) — the MCP initialize handshake is stalling. With the legacy SSE transport the initialize response travels back over the long-lived GET /sse stream, and PaaS proxies (Render included) often buffer or reset that stream so it never reaches the client. Fix: use MCP_TRANSPORT=http (Streamable HTTP, endpoint /mcp), which doesn't depend on a persistent stream and runs stateless by default.

• SSE error: Non-200 status code (421) / Invalid Host header — this is DNS-rebinding protection rejecting the proxy's public hostname. The server disables host checking by default (the bearer token already guards it), so a fresh deploy works out of the box. If you set MCP_ALLOWED_HOSTS, make sure it includes your public host, e.g. your-app.onrender.com.

• GET / → 404 / POST <path> → 405 in the logs — harmless. Each transport serves on its own path (/mcp for Streamable HTTP, /sse + /messages/ for SSE); probes hitting other paths/methods are expected. Point your client at the right path for your transport.

How credits work

• Credits are shared across the web app, browser extension, and API.

• keyword_search costs 1 keywords_search credit per keyword; competitor_analysis 1 per request; ai_search 1 per request; similar_domains 1 per domain (or per project search).

• Credits are only consumed when results are found.

• Always call get_account first to check remaining credits and which features your plan unlocks.

Reading results

Each domain result includes fields you can filter and sort on: title, domain, dr (Ahrefs), tf/cf (Majestic), rd, traffic, ttf0 (topic), ai_lang, gg_news, and per-platform prices (-2 = not found, -1 = price unavailable, >0 = price in the chosen currency). Each platform also has a _url field with the direct purchase link, and best_price_platform names the cheapest one.

License

MIT — see LICENSE.