Vaneform MCP Server

vaneform-mcp

Website traffic lookups for AI assistants and the terminal. This repo has an MCP server, a small CLI and an agent skill for Vaneform, a free website traffic checker.

Ask your assistant "how much traffic does notion.so get?" or "compare figma.com and canva.com" and it answers with estimated monthly visits, month-over-month change, rank, top countries, traffic sources and registry facts. Traffic figures are third-party traffic estimates; see the Vaneform methodology.

中文说明

What's inside

Tools

These tool names and descriptions come from the hosted server's tools/list:

Repeating a domain lookup within 24 hours is free. Site keyword rankings (Pro, 200 credits) are available through the API with include=search.

Free vs Pro

Each key allows 60 requests a minute and 5,000 a day (429 lookup_rate_exceeded above that). See pricing.

Get a free API key

Discovery (initialize, tools/list) is open. Tool calls need a Vaneform API key.

1. Sign in at vaneform.com and create a key at vaneform.com/account/api. A free account is enough.
2. Remote: send Authorization: Bearer vf_live_… or X-API-Key: vf_live_…. Local server and CLI: set VANEFORM_API_KEY.

Without a key, tools still list, and a call returns a sign-up link plus a browser link such as https://vaneform.com/?q=notion.so.

Install

Claude Code (remote)

claude mcp add --transport http --scope user vaneform https://vaneform.com/mcp \
  --header "Authorization: Bearer vf_live_…"

Cursor (remote)

~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "vaneform": {
      "url": "https://vaneform.com/mcp",
      "headers": { "Authorization": "Bearer vf_live_…" }
    }
  }
}

Claude Desktop (local stdio)

The simplest Claude Desktop setup that passes your key is the local proxy. Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "vaneform": {
      "command": "npx",
      "args": ["-y", "github:jiangqizheng/vaneform-mcp"],
      "env": { "VANEFORM_API_KEY": "vf_live_…" }
    }
  }
}

The package isn't on npm yet, so npx installs it from GitHub. The first start takes a little longer because it builds once. If npx exits right away on an old system npm (Debian's packaged npm 9.2 does this with GitHub packages), run npm install -g github:jiangqizheng/vaneform-mcp and use "command": "vaneform-mcp" with no args.

Codex

export VANEFORM_API_KEY=vf_live_…
codex mcp add vaneform --url https://vaneform.com/mcp --bearer-token-env-var VANEFORM_API_KEY

Any other MCP client

• Remote: URL https://vaneform.com/mcp, transport Streamable HTTP, header Authorization: Bearer vf_live_… (or X-API-Key: vf_live_…)
• Local: command npx -y github:jiangqizheng/vaneform-mcp, env VANEFORM_API_KEY

CLI

npx -p github:jiangqizheng/vaneform-mcp vaneform --help
# or clone, then: npm install && npm link
export VANEFORM_API_KEY=vf_live_…
vaneform notion.so                       # traffic overview
vaneform compare notion.so coda.io       # side by side
vaneform tld vaneform --suffixes com,ai,io
vaneform account                         # plan and remaining credits (free)
vaneform notion.so --json                # raw API JSON

Output with no key set:

$ vaneform tools
lookup_domain   Read a cached Vaneform domain snapshot: scale (full-site or search visits), registry, site profile, and link-rank popularity.
get_account     Read the caller plan, website lookup allowance, and credit balance.
lookup_keyword  Read a US/EN keyword brief: monthly searches, difficulty, CPC, and Google occupancy.
compare_bulk    Compare domains side by side.
compare_tld     Compare the same registrable name across suffixes.

$ vaneform github.com
VANEFORM_API_KEY is not set, so this tool cannot call the Vaneform API.
Create a free API key at https://vaneform.com/account/api (100 credits a month; 1 credit per domain).
Check it in a browser instead: https://vaneform.com/?q=github.com

With a key, vaneform <domain> prints visits, MoM change, rank, top countries, sources, registry dates and the report link, followed by Data: Vaneform (third-party traffic estimates).

Talk to the hosted server directly

curl -s https://vaneform.com/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The same key works for the REST API: docs, OpenAPI.

Agent skill

Copy the skill so your assistant knows when to reach for traffic data and how to cite it:

# Claude Code (user-wide)
mkdir -p ~/.claude/skills/website-traffic-lookup
curl -fsSL https://raw.githubusercontent.com/jiangqizheng/vaneform-mcp/main/skills/website-traffic-lookup/SKILL.md \
  -o ~/.claude/skills/website-traffic-lookup/SKILL.md

For other agents that read SKILL.md folders, put it in that agent's skills directory (for example .agents/skills/ in a project). Vaneform also serves a lower-level API skill at vaneform.com/skill.md.

Reading the numbers

• status: "missing" means Vaneform hasn't cached that domain yet. It does not mean zero traffic. compare_bulk fetches it.
• Every estimate carries its month (as_of) and a confidence label. Quote them.
• Cite results as "Vaneform (third-party traffic estimates)".

Development

npm install        # also builds dist/
npm run lint       # biome + tsc
npm test           # unit tests + a stdio test with the official MCP SDK client
VANEFORM_MCP_URL=http://localhost:3000/mcp node dist/bin/vaneform.js tools   # point at another server

The runtime has no dependencies and needs Node 18 or newer. This repo contains only the client. No data collection code lives here.

License

MIT. The license covers this code only, not data returned by the API. Traffic figures are third-party estimates served by Vaneform.