rockygeo-mcp

MCP (Model Context Protocol) server that wraps the RockyGeo IP geolocation API hosted on RapidAPI. Lets MCP-compatible clients (Claude Desktop, Claude Code, etc.) perform IPv4/IPv6 geolocation lookups via tool calls.

Install

npm install
npm run build

Configure

| Variable | Default | Notes | | ------------------------ | --------------------------------------- | ------------------------------------------------------- | | RAPIDAPI_KEY | (required) | Sent as x-rapidapi-key. Override with --api-key <k>. | | ROCKYGEO_BASE_URL | https://rocky-geo.p.rapidapi.com/v1 | Point at a different Rocky Geo API provider. | | ROCKYGEO_RAPIDAPI_HOST | parsed from base URL | Sent as x-rapidapi-host for *.rapidapi.com hosts. |

MCP client setup

Add to your client config (Claude Code ~/.claude.json, Claude Desktop claude_desktop_config.json, etc.):

{
  "mcpServers": {
    "rockygeo": {
      "command": "node",
      "args": ["/Users/cyborg97/rockygeomcp/dist/index.js"],
      "env": { "RAPIDAPI_KEY": "<your-key>" }
    }
  }
}

Tools

• lookup_ip — { ip: string } → geolocation for one IP. Private/reserved IPs return { found: false }.
• lookup_ips_batch — { ips: string[] } (1–100) → { results: { [ip]: ... } }.
• health_check — {} → { status, dataVersion, lastSyncAt, uptime }.

Smoke test with the inspector

RAPIDAPI_KEY=<key> npx @modelcontextprotocol/inspector node dist/index.js

Then in the inspector UI: list tools, run lookup_ip with { "ip": "8.8.8.8" }.

Integration tests

End-to-end tests in tests/integration.test.js spawn the built server as a child process and exercise every tool over the real MCP stdio transport, hitting the live RockyGeo API.

npm test

If RAPIDAPI_KEY is not in the environment, the runner prompts for it (input is hidden). The runner also auto-builds dist/ if it is missing.

Note: tests hit the real upstream API, so they consume RapidAPI quota and may be rate-limited on the Free plan (1 RPS).

License

MIT.