FindIP
OfficialFindIP 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
Tool | What it does | Key |
| Country, city, ISP and ASN for an IP, plus risk signals: VPN, proxy, Tor, relay, hosting, scanner, malicious listings, threat score | API key |
| Server-side risk check for a Shield session: score, recommendation, challenge status, IP and network rotation | Site secret key |
| Your Shield sites with today's event and risky-event counts | API key |
| Recent high-risk events on a site, for example "what risky traffic hit my signup form this week" | API key |
| One event in plain language: where it came from, which signals fired, what was recommended | API key |
| The recipe for adding Shield to a project: keys, framework detection, npm or script tag, how to verify | None |
| Whether an install works, by the site's public key: waiting, test visit from localhost, receiving, or refused and why | None |
All seven 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/mcpClaude 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
Variable | Purpose |
| Your FindIP API key. Required for |
| Secret key ( |
| Set to |
| Request timeout. Default 15000. |
| Override the FindIP hosts, for testing. |
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.netandwww.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 buildLicense
MIT
Available Tools
5 toolsexplain_eventExplain a Shield eventARead-onlyIdempotent
Explains one Shield event in plain language: where it came from, which risk signals fired, the score and recommendation, and what the in-page SDK did. The explanation describes risk signals, not a verdict about the visitor.
Inputs: event_id (required), site.
list_shield_sitesList Shield sitesARead-onlyIdempotent
Lists the FindIP Shield sites on your account: ID, name, domain, status, last event time and today's event and risky-event counts. Start here to find the site to ask about.
Inputs: no named parameters.
lookup_ipLook up an IP addressARead-onlyIdempotent
IP intelligence for one IPv4 or IPv6 address from FindIP: country, city, ISP and ASN, connection type, and risk signals (VPN, proxy, Tor, relay, hosting, scanner, malicious listings, threat score). Signals describe the network an address belongs to, not the person using it.
Inputs: ip (required).
recent_risky_eventsRecent risky eventsARead-onlyIdempotent
Recent events on one Shield site at or above a risk score, newest first: event name, page, IP, country, network, network signals, score, recommendation and reasons. Good for questions like "what risky traffic hit my signup form this week". End-user identity is never returned.
Inputs: site (required), limit, range, event_name, +1 more.
verify_sessionVerify a Shield sessionARead-onlyIdempotent
Server-side risk check for one FindIP Shield session: risk score, recommendation (allow, monitor, challenge, block), whether a challenge was passed, and the session picture (IP, ASN and country rotation, network flags, risk reasons). This is the same check a backend runs before acting on a signup, login or checkout. An unknown session returns verified: false; a session without IP intelligence returns risk_status "unknown", which is not the same as safe. Uses the site secret key from FINDIP_SHIELD_SECRET_KEY.
Inputs: session_id (required), event.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a clearly distinct object and action: raw IP intel (lookup_ip), session risk verdict (verify_session), site inventory (list_shield_sites), site-level event listing (recent_risky_events), and single-event narrative (explain_event). The descriptions explicitly disambiguate the look-alike pair (IP-level vs session-level risk) and clarify that 'unknown' is not 'safe'. The two event tools are separated by list-vs-explain, which is easy for an agent to reason about.
Four of five names follow a verb_noun pattern (lookup_ip, verify_session, list_shield_sites, explain_event). The exception is recent_risky_events, a bare noun phrase with no verb, which breaks the otherwise predictable convention. All are snake_case, so the deviation is minor rather than chaotic.
Five tools is a tight, well-scoped set for an IP intelligence plus Shield session/event domain, and each tool has an evident role. It sits at the low end, with no room for filtering or drill-down variants, which is a slight under-provisioning rather than an excess.
Core read workflows are covered (identify a site, list its risky events, explain one event, check a session, look up an IP), but there are notable gaps: no way to list all events for a site regardless of risk, no event-detail fetch separate from the plain-language explanation, and no session listing or site configuration inspection. An agent asking 'what happened on my site today' or 'show me this specific event's raw data' can hit a dead end.
Maintenance
Related MCP Connectors
IP geolocation, ASN and a 0-100 risk score (VPN, proxy, Tor, datacenter) for any IP address.
51Free IP risk and geolocation lookup: proxy, VPN and datacenter detection. No API key.
IP geolocation, ASN and network data, plus VPN, proxy and Tor detection. ASN tools need no key.
Free no-key IP intelligence: geolocation, VPN detection, DNS, WHOIS, blacklists, breach checks
Related MCP Servers
- AlicenseAqualityDmaintenanceLook up IP address geolocation, network information, detect proxies and VPNs, and find abuse contact details using IPLocate.io634 npm20MIT
- AlicenseNot gradedqualityDmaintenanceEnables IP address intelligence lookup including geolocation, network information, privacy detection (VPN/proxy/Tor), company data, and abuse contacts using IPLocate.io API. Supports both IPv4 and IPv6 addresses with comprehensive analysis tools and security assessment capabilities.34 npmMIT
- AlicenseNot gradedqualityDmaintenanceProvides a no-key IP intelligence API for MCP clients, enabling IP geolocation, VPN/datacenter detection, DNS, WHOIS, blacklist checks, security headers, port scanning, and more.MIT
- AlicenseNot gradedqualityBmaintenanceEnables checking any IP address for VPN, proxy, Tor, datacenter hosting, anonymity, and fraud risk signals, plus API service status, directly from MCP-capable clients like Claude and Cursor.91 npm2MIT