@joinmassive/mcp-server

Official MCP server for the Massive Web Render API. Give your AI agents real-time web access — fetch any URL, search Google, query AI chatbots — with JS rendering, captcha solving, and 195+ country geo-targeting handled automatically.

Quickstart (Claude Desktop)

Option A — One-click install (.mcpb)

1. Download the latest massive-mcp-X.Y.Z.mcpb from GitHub Releases.
2. Open the file with Claude Desktop (or drag-drop into Settings → Extensions).
3. Paste your Massive API token when prompted. Token is stored in your OS keychain.

Option B — npx + config snippet

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "massive": {
      "command": "npx",
      "args": ["-y", "@joinmassive/mcp-server"],
      "env": { "MASSIVE_TOKEN": "your-token-here" }
    }
  }
}

Restart Claude Desktop.

Quickstart (Claude Code)

One command, works across all your projects:

claude mcp add massive --scope user -e MASSIVE_TOKEN=your-token-here -- npx -y @joinmassive/mcp-server

Then /mcp in any Claude Code session to confirm it's connected. Drop --scope user to scope it to the current project only.

Other MCP clients

The same JSON snippet works for any MCP-compatible client. Drop it into the client's config file:

| Client | Config path | |---|---| | Cursor | ~/.cursor/mcp.json | | Continue | ~/.continue/config.json (under mcpServers) | | Cody | ~/Library/Application Support/com.sourcegraph.cody/mcp.json (macOS) | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | VS Code (MCP) | ~/.config/Code/User/settings.json (under chat.mcp.servers) |

If npx isn't on the client's PATH, swap to a direct binary path: "command": "node", "args": ["/absolute/path/to/dist/index.js"].

Getting an API token

Sign in at dashboard.joinmassive.com → Developer → API Keys.

Tools

web_fetch

Fetch any URL. Returns Markdown by default (best for LLMs).

| Arg | Type | Default | Notes | |-----|------|---------|-------| | url | string (required) | — | | | format | "markdown" | "rendered" | "raw" | "markdown" | | | country | string (ISO 3166-1 alpha-2) | — | | | city | string | — | | | subdivision | string | — | ISO 3166-2 (e.g. "TN"). Ignored if city is set. | | device | string | — | Device emulation name | | expiration | integer (0–365) | — | Days the cached result is reused. 0 = always live (good for prices, scores). | | difficulty | "low" | "medium" | "high" | "low" | Anti-bot evasion strength. Multipliers: medium=2×, high=premium. |

Example prompt: "Use the Massive MCP server to fetch https://news.ycombinator.com and summarise the top stories."

web_search

Google search results, parsed into structured JSON.

| Arg | Type | Default | |-----|------|---------| | query (required, ≤ 255 chars) | string | — | | country | string (ISO) | — | | city | string | — | | subdivision | string | — | | max_results | number | 10 | | expiration | integer (0–365) | — | | language | string | — | | display | string | — |

Returns: { organic, ai_overview, people_also_ask, query }.

Example shape:

{
  "query": "best espresso machines 2026",
  "organic": [
    { "title": "...", "url": "https://...", "snippet": "..." }
  ],
  "ai_overview": { "answer": "...", "sources": [{ "domain": "wirecutter.com", "url": "https://..." }] },
  "people_also_ask": [
    { "question": "What is the best espresso machine for beginners?", "answer": "" }
  ]
}

Example prompt: "Use web_search to find recent reviews of espresso machines and return the top 3 organic results plus the AI overview."

ai_chat_completion

Chatbot answer with sources.

| Arg | Type | Default | |-----|------|---------| | prompt (required, ≤ 2047 chars) | string | — | | model | "chatgpt" | "gemini" | "perplexity" | "copilot" | "chatgpt" | | country | string (ISO) | — | | city | string | — | | subdivision | string | — | | expiration | integer (0–365) | — | | language | string | — | | display | string | — | | device | string | — |

Returns: { completion, sources, model, subqueries? }.

account_status

No args. Returns { credits_remaining }. Useful to warn the user before they run out of credits. Free — does not consume credits.

Pricing & cost control

Credit costs (live reference: https://joinmassive.com/pricing):

| Endpoint | Base cost | Notes | | --- | --- | --- | | web_fetch | 1 credit | Multipliers — difficulty=medium → 2×, difficulty=high → premium | | web_search | 1 credit | No multipliers | | ai_chat_completion | 1 credit | No multipliers | | account_status | Free | — |

Worked example: web_fetch with difficulty=medium costs 1 × 2 = 2 credits.

Tips for keeping costs down

• Cache: expiration (days) reuses recent results. Default 1. Set expiration=0 only when freshness matters (prices, scores, weather).
• Difficulty: start with default low. Bump to medium / high only if the low attempt fails.
• Check first: call account_status (free) before launching a batch.

Resources

This server exposes three read-only reference documents at docs:// URIs. They show up in your MCP client as attachable references:

| URI | Contents | | --- | --- | | docs://massive/pricing | Credit costs and multipliers (same as the table above, inline in your client) | | docs://massive/geotargeting | 190+ countries, subdivision/city format, examples | | docs://massive/changelog | What's new in each release |

In Claude Desktop: open the Connectors panel and pick the resource from this server. In Claude Code: type @ and search by name. The model does not auto-read these — they're for you to browse.

Troubleshooting

"MASSIVE_TOKEN env var is not set" Confirm the env block in your Claude Desktop config has the token. Restart Claude Desktop.

"Massive endpoint is autoscaling, please retry" A 503 from upstream. The server already retried once; wait ~10s and try again.

"403 Forbidden — the request was rejected (likely captcha or invalid token)" Either the target site rejected our captcha solver, or the token is invalid. Re-check the token at the dashboard.

No tools appear in Claude Desktop Settings → Developer → check the MCP server logs. The most common cause is command: "npx" not being on Claude Desktop's PATH. Run which npx in Terminal — if it's under Homebrew (/opt/homebrew/bin), Claude Desktop's PATH won't include it. As a workaround, use a direct path: "command": "node", "args": ["/absolute/path/to/dist/index.js"]. Or install the .mcpb bundle (Option A above), which sidesteps PATH issues entirely.

Contributing

Issues and PRs welcome at github.com/joinmassive/mcp-server.

License

MIT. See LICENSE.