apifreaks-mcp

# @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 instantly query live weather, domains, IPs, DNS records, SSL certs, currency rates, commodity prices, screenshots, PDFs, web scrapes, VAT/IBAN/SWIFT, email 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."* |
| 📡 | *"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) |
| `APIFREAKS_MODULES` | Yes | Comma-separated list of modules to expose. If unset or empty, only `list_modules` is listed (no API tools). 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 actually need.

Set `APIFREAKS_MODULES` in your MCP client config. Only those modules are registered, so `tools/list` returns just that subset. If the variable is missing or empty, no API tools are listed — only `list_modules`. Call it to see each module and the tools inside it, then paste a full `APIFREAKS_MODULES=...` line (every module you want, not only the new name) and restart.

```bash
APIFREAKS_MODULES=ip-intelligence,currency,whois,dns,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` | Single and bulk email validation |
| `phone-validation` | Single and bulk phone validation |
| `ssl` | Live certificate and full chain |
| `domain` | Availability checks, suggestions, bulk, subdomain lookup |
| `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, 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 APIFREAKS_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 APIFREAKS_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",
        "APIFREAKS_MODULES": "ip-intelligence,currency,whois,dns,weather"
      }
    }
  }
}
```

---

### Codex CLI

```bash
codex mcp add apifreaks --env APIFREAKS_API_KEY=your_apikey_here --env APIFREAKS_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",
        "APIFREAKS_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",
        "APIFREAKS_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",
        "APIFREAKS_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",
        "APIFREAKS_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",
        "APIFREAKS_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",
        "APIFREAKS_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",
        "APIFREAKS_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 Gl