FindIP MCP server

Ask your assistant about an IP address or a risky session, and get the answer from FindIP.

@findip/mcp is a Model Context Protocol server for FindIP. It gives Claude, Cursor and other MCP clients IP intelligence and FindIP Shield risk signals. It runs locally over stdio and only reads data.

Tools

All five tools are read-only. docs/BACKEND.md lists the FindIP endpoint behind each one.

Related MCP server: IPLocate MCP Server

Setup

You need Node.js 18.17 or later and a FindIP API key. Keys are free at findip.net.

Claude Code

claude mcp add findip --env FINDIP_API_KEY=your_api_key -- npx -y @findip/mcp

Claude Desktop

Add this to claude_desktop_config.json (Settings, Developer, Edit Config), then restart Claude Desktop:

{
  "mcpServers": {
    "findip": {
      "command": "npx",
      "args": ["-y", "@findip/mcp"],
      "env": {
        "FINDIP_API_KEY": "your_api_key"
      }
    }
  }
}

Cursor

Add this to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

{
  "mcpServers": {
    "findip": {
      "command": "npx",
      "args": ["-y", "@findip/mcp"],
      "env": {
        "FINDIP_API_KEY": "your_api_key"
      }
    }
  }
}

Configuration

The Shield account tools allow 60 requests per account per minute. Repeated requests with a wrong key are blocked for 10 minutes.

Keys are read from the environment only. They are never accepted as tool arguments and never appear in tool output or error messages.

Examples

• "Look up 203.0.113.9. Is it a VPN or a hosting provider?"

• "Verify Shield session sess_8f2c and tell me why it was flagged."

• "What risky traffic hit my signup form this week?"

• "Explain event 5b1e... on shop.example. Should I worry?"

How to read the results

FindIP reports risk signals. A VPN, a hosting network or a high score tells you about the connection, not about the person behind it. Use the signals to decide who gets a closer look, an extra step or a manual review.

The Shield browser SDK collects signals and can add friction in the page, but a browser can be scripted or bypassed, so it is not a security boundary. Decisions that matter belong on your server: call server verification (the endpoint verify_session uses) from your backend before you allow, challenge or block. A session with risk_status: "unknown" had no IP intelligence; treat it as unknown, not as safe.

Privacy

• The server talks only to FindIP: api.findip.net, shield.findip.net and www.findip.net.

• Shield tools never return end-user identity (email, user ID and their hashes). FindIP removes it before the data leaves its servers.

• Site listings are a short summary: no site keys, no settings.

• No telemetry, and nothing is written to disk.

Development

npm install
npm run typecheck
npm test        # vitest, all HTTP mocked
npm run build

License

MIT