# @apifreaks/mcp

[![npm version](https://img.shields.io/npm/v/@apifreaks/mcp?logo=npm&label=npm&color=CB3837)](https://www.npmjs.com/package/@apifreaks/mcp)
[![GitHub release](https://img.shields.io/github/v/release/api-freaks/apifreaks-mcp?logo=github&label=release&color=181717)](https://github.com/api-freaks/apifreaks-mcp/releases)
[![Glama](https://glama.ai/mcp/servers/api-freaks/apifreaks-mcp/badges/score.svg)](https://glama.ai/mcp/servers/api-freaks/apifreaks-mcp)
[![Node.js](https://img.shields.io/badge/node-%3E%3D24-5FA04E?logo=node.js&logoColor=white)](https://nodejs.org)
[![CI](https://github.com/api-freaks/apifreaks-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/api-freaks/apifreaks-mcp/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache%202.0-16A34A)](https://github.com/api-freaks/apifreaks-mcp/blob/main/LICENSE)

The official [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [APIFreaks](https://apifreaks.com). Add it to Claude, Cursor, Windsurf, or any MCP-compatible client and your AI can query live weather, WHOIS, DNS, SSL, domain availability / reputation / typosquatting, IP geolocation and threat intel, currency, commodities, screenshots, PDFs, VAT/IBAN/SWIFT, email validation, disposable-email checks, and phone validation, geocoding, and more.

**What can you ask once it's connected?**

| | |
|---|---|
| 🌦 | *"What's the 7-day forecast for Tokyo and should I bring an umbrella?"* |
| 🔒 | *"Check stripe.com's SSL cert — is it valid and when does it expire?"* |
| 🌍 | *"Who registered openai.com and when? Has the WHOIS record changed recently?"* |
| 💱 | *"Convert 2500 USD to EUR, GBP, and JPY at today's live rate."* |
| 🔍 | *"Check if these 20 domain names are available for registration."* |
| 🛡 | *"Is paypal-login.xyz risky? What's its domain reputation and trust score?"* |
| 🕵 | *"Find typosquat domains for the brand paypal."* |
| 📡 | *"What DNS records does github.com have? Show me the full MX and TXT records."* |

---

## Table of Contents

- [Requirements](#requirements)
- [Environment Variables](#environment-variables)
- [Modules](#modules)
- [Getting Your API Key](#getting-your-api-key)
- [Quick Start](#quick-start)
- [Integration Guides](#integration-guides)
  - [Claude Code](#claude-code)
  - [Codex CLI](#codex-cli)
  - [Claude Desktop](#claude-desktop)
  - [Cursor](#cursor)
  - [Windsurf](#windsurf)
  - [Cline](#cline)
  - [OpenCode](#opencode)
  - [Gemini CLI](#gemini-cli)
  - [VS Code](#vs-code-github-copilot--continue)
  - [Glama](#glama)
- [Available Tools](#available-tools)
- [Support](#support)
- [License](#license)
- [Privacy Policy](#privacy-policy)

---

## Requirements

- [Node.js](https://nodejs.org) v24 or higher
- An APIFreaks API key — [sign up free](https://apifreaks.com)

---

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `APIFREAKS_API_KEY` | Yes | Your APIFreaks API key — get one at [apifreaks.com](https://apifreaks.com) |
| `ENABLE_MODULES` | Yes | Comma-separated modules to expose. Without it only `list_modules` is available — call it to see modules/tools and how to enable more. See [Modules](#modules). |

---

## Modules

This server covers many APIs. Advertising all of them in `tools/list` would fill the client's context window, so you opt in to the modules you need.

Set `ENABLE_MODULES` in your MCP client config. Only those modules are registered. If it is missing or empty, only `list_modules` is available — call it to see every module and a paste-ready `ENABLE_MODULES=...` line (keep existing modules, append new ones), then restart.

```bash
ENABLE_MODULES=ip-intelligence,whois,dns,domain,weather
```

Hyphens and underscores are interchangeable (`user-agent` and `user_agent` both work). Unknown names are ignored and logged to stderr.

| Module | Tools |
|---|---|
| `ip-intelligence` | IP geolocation and threat intelligence (single + bulk) |
| `geocoding` | Forward and reverse geocoding |
| `whois` | Domain, IP, ASN, history, reverse, bulk |
| `dns` | Live lookup, history, reverse, bulk |
| `scraper` | Static HTML scrape and JS-rendered scrape |
| `email-validation` | Validation and disposable checks (single + bulk) |
| `phone-validation` | Single and bulk phone validation |
| `ssl` | Live certificate and full chain |
| `domain` | Availability, suggestions, bulk, subdomain, reputation, typosquatting |
| `screenshot` | Capture, scrolling capture, bulk |
| `pdf` | Merge, split, compress, protect, generate, convert |
| `currency` | Live/historical rates, converters, time series, symbols, limits |
| `commodity` | Live/historical prices (245+), fluctuation, time series, symbols |
| `financial` | VAT rates, VAT numbers, IBAN, SWIFT/BIC |
| `zipcode` | Lookup, radius, distance, city/region |
| `weather` | Current, forecast, historical, air quality, marine, flood, astronomy |
| `geography` | Admin units, countries, cities, regions, flags |
| `timezone` | Lookup and convert |
| `user-agent` | Parse single or bulk user-agent strings |

---

## Getting Your API Key

Sign in or create a free account at [apifreaks.com](https://apifreaks.com). Your API key is in the dashboard under **API Keys**.

Full API documentation: [apifreaks.com/docs](https://apifreaks.com/docs)

---

## Quick Start

The fastest way to connect it — via the Claude Code CLI:

```bash
claude mcp add apifreaks -e APIFREAKS_API_KEY=your_apikey_here -e ENABLE_MODULES=ip-intelligence,currency,whois,dns,weather -- npx -y @apifreaks/mcp
```

Replace `ip-intelligence,currency,whois,dns,weather` with the [modules](#modules) you need. For Cursor, Windsurf, Cline, and others see the [Integration Guides](#integration-guides) below.

---

## Integration Guides

### Claude Code

**Via terminal (recommended):**

```bash
claude mcp add apifreaks -e APIFREAKS_API_KEY=your_apikey_here -e ENABLE_MODULES=ip-intelligence,currency,whois,dns,weather -- npx -y @apifreaks/mcp
```

**Via config file** (`~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "apifreaks": {
      "command": "npx",
      "args": ["-y", "@apifreaks/mcp"],
      "env": {
        "APIFREAKS_API_KEY": "your_apikey_here",
        "ENABLE_MODULES": "ip-intelligence,currency,whois,dns,weather"
      }
    }
  }
}
```

---

### Codex CLI

```bash
codex mcp add apifreaks --env APIFREAKS_API_KEY=your_apikey_here --env ENABLE_MODULES=ip-intelligence,currency,whois,dns,weather -- npx -y @apifreaks/mcp
```

Start a new Codex session after adding the server.

---

### Claude Desktop

Edit `claude_desktop_config.json`:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "apifreaks": {
      "command": "npx",
      "args": ["-y", "@apifreaks/mcp"],
      "env": {
        "APIFREAKS_API_KEY": "your_apikey_here",
        "ENABLE_MODULES": "ip-intelligence,currency,whois,dns,weather"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

---

### Cursor

Create or edit `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global):

```json
{
  "mcpServers": {
    "apifreaks": {
      "command": "npx",
      "args": ["-y", "@apifreaks/mcp"],
      "env": {
        "APIFREAKS_API_KEY": "your_apikey_here",
        "ENABLE_MODULES": "ip-intelligence,currency,whois,dns,weather"
      }
    }
  }
}
```

Or go to **Cursor Settings → MCP** and add the server via the UI.

---

### Windsurf

Edit `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "apifreaks": {
      "command": "npx",
      "args": ["-y", "@apifreaks/mcp"],
      "env": {
        "APIFREAKS_API_KEY": "your_apikey_here",
        "ENABLE_MODULES": "ip-intelligence,currency,whois,dns,weather"
      }
    }
  }
}
```

---

### Cline

Open the **MCP Servers** panel in Cline, click **Configure**, then **Advanced MCP Settings** to open `cline_mcp_settings.json`. Or edit it directly:

- **macOS:** `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- **Linux:** `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- **Windows:** `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`

```json
{
  "mcpServers": {
    "apifreaks": {
      "command": "npx",
      "args": ["-y", "@apifreaks/mcp"],
      "env": {
        "APIFREAKS_API_KEY": "your_apikey_here",
        "ENABLE_MODULES": "ip-intelligence,currency,whois,dns,weather"
      }
    }
  }
}
```

Restart Cline after saving.

---

### OpenCode

Edit `~/.config/opencode/config.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "apifreaks": {
      "type": "local",
      "command": ["npx", "-y", "@apifreaks/mcp"],
      "environment": {
        "APIFREAKS_API_KEY": "your_apikey_here",
        "ENABLE_MODULES": "ip-intelligence,currency,whois,dns,weather"
      }
    }
  }
}
```

---

### Gemini CLI

Edit `~/.gemini/settings.json` (or `.gemini/settings.json` in your project root for project-level config):

```json
{
  "mcpServers": {
    "apifreaks": {
      "command": "npx",
      "args": ["-y", "@apifreaks/mcp"],
      "env": {
        "APIFREAKS_API_KEY": "your_apikey_here",
        "ENABLE_MODULES": "ip-intelligence,currency,whois,dns,weather"
      }
    }
  }
}
```

---

### VS Code (GitHub Copilot / Continue)

Create `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "apifreaks": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@apifreaks/mcp"],
      "env": {
        "APIFREAKS_API_KEY": "your_apikey_here",
        "ENABLE_MODULES": "ip-intelligence,currency,whois,dns,weather"
      }
    }
  }
}
```

---

### Glama

The APIFreaks MCP server is listed on [Glama](https://glama.ai/mcp/servers/api-freaks/apifreaks-mcp). Glama provides one-click connection and automatic configuration for Claude Desktop and other MCP clients, along with regular security scans and tool quality scoring.

Click **Connect** on the Glama listing page and follow the prompts — it will generate the correct config for your client automatically.

---

## Available Tools

### `list_modules` (always available)

Module catalog for opt-in `ENABLE_MODULES`. Call when a capability is missing from the tool list or to check coverage. Live tools already appear in `tools/list`; use `needs_enable[].enable_line` for a paste-ready config line, then restart.

---

### IP Intelligence (`ip-intelligence`) — 4 tools

Geolocation, ISP, network, and threat data for any IP address.

| Tool | Description |
|---|---|
| `ipgeolocation_lookup` | Location, ASN, company, currency, timezone for an IP or hostname |
| `ipgeolocation_bulk_lookup` | Same geolocation data for up to 50,000 IPs in one request |
| `ip_security_lookup` | Threat score plus VPN/proxy/Tor/bot/spam/cloud/gateway signals for one IP |
| `ip_security_bulk_lookup` | Same threat intelligence for up to 50,000 IPs in one request |

---

### Geocoding (`geocoding`) — 2 tools

Address ↔ coordinate conversion.

| Tool | Description |
|---|---|
| `geocode_forward` | Convert an address or place name into coordinates |
| `geocode_reverse` | Convert coordinates into a street address |

---

### WHOIS (`whois`) — 6 tools

Domain and IP ownership data including historical records.

| Tool | Description |
|---|---|
| `whois_domain_lookup` | Live WHOIS record for a domain name |
| `whois_ip_lookup` | WHOIS ownership and network data for an IPv4 or IPv6 address |
| `whois_asn_lookup` | WHOIS data for an Autonomous System Number (ASN) |
| `whois_domain_history` | Historical WHOIS snapshots for a domain (data back to 1986) |
| `whois_reverse_lookup` | Search WHOIS records by owner name, email, company, or keyword |
| `whois_bulk_domain_lookup` | Live WHOIS data for up to 100 domains at once |

---

### DNS (`dns`) — 4 tools

Live DNS records, history, and reverse lookups.

| Tool | Description |
|---|---|
| `dns_lookup` | Real-time DNS records for a hostname — A, AAAA, MX, NS, TXT, CNAME, SOA, SPF |
| `dns_history` | Historical DNS record snapshots for a hostname |
| `dns_reverse` | Find all hostnames pointing to a specific DNS record value |
| `dns_bulk_lookup` | Real-time DNS records for up to 100 hostnames at once |

---

### Scraper (`scraper`) — 2 tools

Extract HTML or structured fields from a URL. Static mode first; JS rendering only when the page needs a browser.

| Tool | Description |
|---|---|
| `scraper_scrape` | Scrape static HTML (optional extract / form submit). Empty instructions return the full page |
| `scraper_scrape_js` | Scrape with JavaScript rendering, browser steps, proxies, and optional CAPTCHA solving |

---

### Email Validation (`email-validation`) — 4 tools

Deliverability, syntax, domain, optional IP enrichment, and disposable-provider checks.

| Tool | Description |
|---|---|
| `email_validate` | Validate a single email address |
| `email_bulk_validate` | Validate up to 100 email addresses in one request |
| `email_disposable_check` | Check whether one address is throwaway, free, spam-listed, or role-based, and whether its domain has mail servers |
| `email_bulk_disposable_check` | Run the disposable check on up to 100 addresses in one request |

---

### Phone Validation (`phone-validation`) — 2 tools

Carrier, line type, location, and standardized formats.

| Tool | Description |
|---|---|
| `phone_validate` | Validate a single phone number |
| `phone_bulk_validate` | Validate up to 100 phone numbers in one request |

---

### SSL (`ssl`) — 2 tools

Live SSL certificate data for any domain.

| Tool | Description |
|---|---|
| `ssl_live_lookup` | Retrieve the live SSL certificate for a domain |
| `ssl_live_chain_lookup` | Retrieve the complete SSL certificate chain for a domain |

---

### Domain (`domain`) — 6 tools

Domain availability checks with bulk support, suggestions, subdomain discovery, reputation assessment, and typosquatting search.

| Tool | Description |
|---|---|
| `domain_check_availability` | Check whether a domain name is available for registration |
| `domain_check_availability_with_suggestions` | Check availability and get alternative domain suggestions |
| `domain_subdomain_lookup` | Paginated list of discovered subdomains for a domain |
| `domain_bulk_check_availability` | Check availability for up to 100 domains at once |
| `domain_reputation_lookup` | Risk verdict, trust score, DGA, threat feeds, and email deliverability for a domain |
| `domain_typosquatting_lookup` | Find registered typo/look-alike domains for a brand keyword or wildcard pattern |

---

### Screenshot (`screenshot`) — 3 tools

Capture screenshots and scrolling recordings of any webpage.

| Tool | Description |
|---|---|
| `screenshot_capture` | Capture a screenshot of a webpage and return the image URL |
| `screenshot_bulk_capture` | Capture screenshots of up to 50 webpages in one request |
| `screenshot_capture_scrolling` | Record a scrolling video or animated GIF of a webpage |

---

### PDF (`pdf`) — 20 tools

Merge, split, extract or remove pages, convert to images, generate from templates, compress, rotate, encrypt/restrict, decrypt/unrestrict, and linearize.

Jobs (merge, split, convert, …) are asynchronous: they return a `taskId`. Check progress with `pdf_task_status`. Local files need an **absolute** path (the MCP server reads the disk). You can also pass a stored `file_id`. Template generation (`pdf_generate`, `pdf_generate_bulk`) is synchronous and returns a hosted `pdf_url`.

Completed jobs include download URLs. Add your API key as the `apiKey` query parameter or the `X-apiKey` header.

| Tool | Description |
|---|---|
| `pdf_merge` | Merge PDFs (local paths and/or stored file IDs) |
| `pdf_split` | Split a PDF by page ranges |
| `pdf_extract_pages` | Extract pages into a new PDF or ZIP |
| `pdf_remove_pages` | Remove pages from a PDF |
| `pdf_to_image` | Convert pages to PNG, JPG, TIFF, BMP, or GIF |
| `pdf_generate` | Render a template with JSON and get a hosted PDF URL |
| `pdf_generate_bulk` | Render one PDF per CSV row |
| `pdf_compress` | Reduce PDF file size |
| `pdf_rotate` | Rotate pages |
| `pdf_encrypt` | Password-protect a PDF |
| `pdf_restrict` | Restrict printing, copying, and editing |
| `pdf_decrypt` | Remove encryption |
| `pdf_unrestrict` | Remove permission restrictions |
| `pdf_linearize` | Linearize for Fast Web View |
| `pdf_task_status` | Check one async job (`queued` / `processing` / `completed` / `failed`) |
| `pdf_file_status` | Metadata for a stored file |
| `pdf_files` | List stored PDFs |
| `pdf_file_delete` | Delete a stored PDF |
| `pdf_upload` | Upload local PDFs and get file IDs |
| `pdf_upload_binary` | Upload one large PDF as raw bytes and get a file ID |

---

### Currency (`currency`) — 12 tools

Live and historical exchange rates for 170+ fiat currencies and 830+ cryptocurrencies.

| Tool | Description |
|---|---|
| `currency_latest_rates` | Latest exchange rates for all supported currencies |
| `currency_historical_rates` | Exchange rates for a specific past date |
| `currency_latest_converter` | Convert an amount between currencies using live rates |
| `currency_historical_converter` | Convert using rates from a specific past date |
| `currency_time_series` | Day-by-day exchange rates over a custom date range |
| `currency_fluctuation` | Rate fluctuation metrics and percentage change over a period |
| `currency_geo_convert` | Convert to the local currency of an IP address's country |
| `currency_supported` | Full list of supported currencies with metadata |
| `currency_symbols` | Map of currency symbols to currency names |
| `currency_symbol_info` | Validate a currency symbol and get its full name |
| `currency_historical_data_limits` | Historical data availability window for every currency |
| `currency_historical_data_limit_info` | Historical data availability window for one currency code |

---

### Commodity (`commodity`) — 7 tools

Real-time and historical prices for 245+ commodities across metals, energy, agriculture, and more. If some symbols cannot be resolved, the API returns a partial result with an `unresolved` map instead of failing the whole request.

| Tool | Description |
|---|---|
| `commodity_latest_rates` | Latest prices (per-symbol updateInterval), optionally converted to a quote currency |
| `commodity_historical_rates` | Historical OHLC prices for a specific date (from 1990; falls back to last available earlier date) |
| `commodity_fluctuation` | Start/end price, absolute change, and percent change over a date range (no range-length limit) |
| `commodity_time_series` | Daily OHLC prices over a date range (up to 365 days; non-trading days excluded) |
| `commodity_symbols` | List all supported commodity symbols with metadata, including each symbol's updateInterval |
| `commodity_symbol_info` | Look up one symbol (refresh cadence, status, unit, currency) |
| `commodity_quotes` | List all supported quote currencies for commodity pricing |

---

### Financial (`financial`) — 9 tools

VAT rates, VAT-number checks, IBAN validation, and SWIFT/BIC lookup.

| Tool | Description |
|---|---|
| `financial_vat_rates_by_country` | VAT rates for a country, optionally by state |
| `financial_vat_rates_bulk` | VAT rates for up to 100 countries/states |
| `financial_vat_rates_by_ip` | VAT rates for the country resolved from an IP address |
| `financial_vat_validate` | Validate an EU (VIES) or UK (HMRC) VAT number |
| `financial_iban_validate` | Validate an IBAN (format, checksum, bank/SEPA metadata) |
| `financial_swift_lookup` | Bank details for an 8- or 11-character SWIFT/BIC code |
| `financial_swift_finder` | Drill down country → bank → city → SWIFT/BIC codes |
| `financial_supported_countries` | Countries (and VAT states) supported by VAT, IBAN, and SWIFT APIs |
| `financial_supported_country_info` | Check whether one country is supported by VAT, IBAN, and/or SWIFT |

---

### ZIP Code (`zipcode`) — 7 tools

Postal code lookups, radius searches, and distance calculations worldwide.

| Tool | Description |
|---|---|
| `zipcode_lookup` | Look up a ZIP or postal code — city, region, country, coordinates |
| `zipcode_radius_search` | Find all ZIP codes within a given radius of a center point |
| `zipcode_distance` | Calculate distance from a base point to up to 100 ZIP codes |
| `zipcode_by_city` | Get all ZIP/postal codes for a city |
| `zipcode_bulk_lookup` | Look up up to 100 ZIP/postal codes at once |
| `zipcode_distance_match` | Find all ZIP code pairs within a given distance threshold |
| `zipcode_by_region` | Get all ZIP/postal codes for a state, province, or region |

---

### Weather (`weather`) — 9 tools

Real-time conditions, forecasts, historical data, environmental monitoring, and astronomy.

| Tool | Description |
|---|---|
| `weather_current` | Current weather for any location — temperature, humidity, wind, pressure, AQI |
| `weather_forecast` | Forecast up to 16 days ahead with daily, hourly, or minutely precision |
| `weather_historical` | Historical weather for any past date (data back to 1940) |
| `weather_time_series` | Historical weather over a custom date range |
| `weather_air_quality` | Real-time or forecast air quality index and pollutant breakdown |
| `weather_marine` | Marine and ocean weather, real-time or forecast up to 16 days |
| `weather_flood_forecast` | Flood forecast with river discharge and flow percentile data |
| `weather_bulk_current` | Current weather for up to 50 locations in one request |
| `astronomy_lookup` | Sunrise, sunset, moon phase, twilight, golden hour, solar noon, moonrise, and sun/moon positions |

---

### Geography (`geography`) — 10 tools

Countries, cities, administrative units, regions, and flag images.

| Tool | Description |
|---|---|
| `geodb_admin_levels` | Administrative level types for a country |
| `geodb_admin_units` | States, provinces, and other admin units for a country |
| `geodb_admin_unit_details` | Details for one administrative unit |
| `geodb_countries` | List countries with ISO codes, capitals, and regions |
| `geodb_country_details` | Full metadata for one country by alpha-2 code |
| `geodb_cities` | Cities for a country, optionally filtered by admin unit |
| `geodb_regions` | List GeoDB regions (Africa, Americas, Asia, Europe, Oceania, Polar) |
| `geodb_subregions` | List subregions, optionally filtered by region |
| `geodb_flags_supported` | Supported country and organization flag identifiers |
| `geodb_flag` | Retrieve a country or organization flag image |

---

### Timezone (`timezone`) — 2 tools

Timezone lookups and conversions using any location identifier.

| Tool | Description |
|---|---|
| `timezone_lookup` | Timezone info for a location — accepts IP, city, lat/long, IATA, ICAO, or UN/LOCODE |
| `timezone_convert` | Convert a date and time from one timezone to another |

---

### User Agent (`user-agent`) — 2 tools

Parse user-agent strings to extract browser, OS, and device information.

| Tool | Description |
|---|---|
| `user_agent_parse` | Parse a user-agent string — browser, device, OS, engine |
| `user_agent_bulk_parse` | Parse up to 20,000 user-agent strings in a single request |

---

## Support

- **Email:** support@apifreaks.com
- **Status:** [status.apifreaks.com](https://status.apifreaks.com)
- **Issues:** [github.com/api-freaks/apifreaks-mcp/issues](https://github.com/api-freaks/apifreaks-mcp/issues)

---

## License

This project is licensed under the [Apache License 2.0](./LICENSE). You are free to use, modify, and distribute this software in accordance with the terms of the license.

---

## Privacy Policy

Your API requests are processed by APIFreaks in accordance with their privacy policy. See [apifreaks.com/privacy-policy](https://apifreaks.com/privacy-policy) for details on how data is collected and handled.