Skip to main content
Glama

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

Tool

What it does

Key

lookup_ip

Country, city, ISP and ASN for an IP, plus risk signals: VPN, proxy, Tor, relay, hosting, scanner, malicious listings, threat score

API key

verify_session

Server-side risk check for a Shield session: score, recommendation, challenge status, IP and network rotation

Site secret key

list_shield_sites

Your Shield sites with today's event and risky-event counts

API key

recent_risky_events

Recent high-risk events on a site, for example "what risky traffic hit my signup form this week"

API key

explain_event

One event in plain language: where it came from, which signals fired, what was recommended

API key

shield_install_recipe

The recipe for adding Shield to a project: keys, framework detection, npm or script tag, how to verify

None

shield_install_status

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/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

Variable

Purpose

FINDIP_API_KEY

Your FindIP API key. Required for lookup_ip, list_shield_sites, recent_risky_events and explain_event.

FINDIP_SHIELD_SECRET_KEY

Secret key (sec_...) of one Shield site. Required for verify_session. Find it in the site's settings in the Shield dashboard.

FINDIP_SHIELD_ACCOUNT_API

Set to 0 to turn off the three Shield account tools, so the API key is used for IP lookups only. On by default.

FINDIP_TIMEOUT_MS

Request timeout. Default 15000.

FINDIP_API_BASE_URL, FINDIP_SHIELD_BASE_URL, FINDIP_PORTAL_BASE_URL

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.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

Available Tools

5 tools
explain_eventExplain a Shield eventA
Read-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 sitesA
Read-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 addressA
Read-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 eventsA
Read-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 sessionA
Read-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

    A4/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Look up IP address geolocation, network information, detect proxies and VPNs, and find abuse contact details using IPLocate.io
      6
      34 npm
      20
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      2
      MIT