mcp-ipinfo: Instructions file for Claude Code

IPInfo MCP Server

MCP server providing IP intelligence via IPInfo API.

Architecture

src/mcp_ipinfo/
├── server.py      # MCP tools (FastMCP) + stdio entrypoint
├── api_client.py  # Async HTTP client
└── api_models.py  # Pydantic models

Critical

• Package name: @nimblebraininc/ipinfo (npm-style, matches GitHub org)
• Manifest uses module execution: python -m mcp_ipinfo.server
• Server needs both entrypoints:

  app = mcp.http_app()  # HTTP deployment
  if __name__ == "__main__":
      mcp.run()  # Stdio for Claude Desktop / mpak
  

Skill Resource

The server embeds an MCP skill as a skill:// resource, served alongside tools:

• URI: skill://ipinfo/usage
• Source: Mirrors the skill published at mpak.dev/skills/@nimblebraininc/ipinfo
• Skill file: src/mcp_ipinfo/SKILL.md (tool selection, context reuse, VPN detection)
• Server instructions: Point the LLM to read the resource before using tools
• Loading: SKILL_CONTENT = files("mcp_ipinfo").joinpath("SKILL.md").read_text() in server.py

user_config

API token configured via manifest user_config, not hardcoded:

{
  "user_config": {
    "api_key": {
      "type": "string",
      "sensitive": true,
      "required": false
    }
  },
  "server": {
    "mcp_config": {
      "env": { "IPINFO_API_TOKEN": "${user_config.api_key}" }
    }
  }
}

Key APIs

API	Endpoint	Used By
Plus (primary)	api.ipinfo.io/lookup/{ip}	get_plus_ip_info()
Core	ipinfo.io/{ip}	get_ip_info(), batch_lookup()
Residential proxy	/resproxy/{ip}	get_residential_proxy_info()
Domains	/domains/{ip}	get_hosted_domains()
Ranges	/ranges/{domain}	get_ip_ranges()
Abuse	/{ip}/abuse	get_abuse_contact()
WHOIS	/whois/net/{ip}	whois_lookup_by_*()

Privacy detection (VPN/proxy/Tor) is ONLY available via Plus API.

Testing

uv run pytest tests/ -v                          # Unit tests (includes skill resource tests)
uv run pytest tests-integration/test_skill_llm.py -v  # LLM smoke tests (needs ANTHROPIC_API_KEY)
uv run ruff check src/ tests/                    # Lint
uv run mypy src/                                 # Type check