Internet.bs MCP Server

A complete Model Context Protocol server for the Internet.bs domain registrar API.

47 tools covering 100% of the Internet.bs API:

Prerequisites

1. An Internet.bs account — Sign up at internet.bs

2. API credentials — Go to your account settings and request API access. You'll receive an API Key and a Password

3. An MCP-compatible client (see Compatibility)

No account yet? You can try everything with the free sandbox — see Test Mode below.

Related MCP server: dynadot-mcp

Important: IP Whitelisting

Internet.bs requires you to whitelist an IP address when creating an API key. Only requests coming from that IP will be accepted. This has important implications depending on how you run this MCP server:

How to find your IP address

Run one of these commands in your terminal:

curl -s ifconfig.me        # Linux / Mac / WSL
curl -s api.ipify.org      # Alternative (IPv4 only)

Or visit whatismyip.com in your browser.

Important: Use your IPv4 address, not IPv6. If ifconfig.me returns an IPv6 (e.g. 2a02:...), use curl -s api.ipify.org instead to get your IPv4.

Local mode (npx) — recommended

You run the server on your own machine. Whitelist your residential/office IP (the public IPv4 of the machine running Claude Code).

If your ISP changes your IP (common with residential connections), you'll need to update the whitelisted IP in your Internet.bs account, or create a new API key.

Self-hosted remote mode (your own server)

You run the server on a VPS/dedicated server. Whitelist the server's fixed IP.

To find the server's outbound IP:

curl -s api.ipify.org    # Run this on the server

This works well with servers that have a static IP (OVH, Hetzner, Contabo, etc.). It does NOT work with serverless platforms like Cloudflare Workers, Vercel, or AWS Lambda, because they use shared/rotating IPs that can't be whitelisted.

Multiple environments

If you need to use the API from multiple IPs (e.g., your PC + a server), you have two options:

1. Create multiple API keys — one per IP, each whitelisted for its own IP

2. Update the whitelisted IP — in your Internet.bs account when you switch environments

Option 1 — Local (via npx) — Recommended

Runs entirely on your machine. Nothing to install besides Node.js.

{
  "mcpServers": {
    "internetbs": {
      "command": "npx",
      "args": ["-y", "internetbs-mcp"],
      "env": {
        "INTERNETBS_API_KEY": "your-api-key",
        "INTERNETBS_PASSWORD": "your-password",
        "INTERNETBS_API_URL": "https://api.internet.bs"
      }
    }
  }
}

Replace your-api-key and your-password with your credentials. Requires Node.js >= 18.

Option 2 — Self-hosted remote (your own server)

Deploy on any server with a fixed IP address. Users connect via URL and pass their own credentials in headers. The server is a stateless proxy — it never stores credentials.

{
  "mcpServers": {
    "internetbs": {
      "url": "https://your-server.com/mcp",
      "headers": {
        "X-InternetBS-Key": "your-api-key",
        "X-InternetBS-Password": "your-password"
      }
    }
  }
}

See Self-Hosting for deployment instructions.

Warning: Serverless platforms (Cloudflare Workers free tier, Vercel, AWS Lambda) do NOT have fixed IPs. They are incompatible with Internet.bs IP whitelisting. Use a VPS with a static IP instead.

Option 3 — Docker

{
  "mcpServers": {
    "internetbs": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "INTERNETBS_API_KEY=your-api-key",
        "-e", "INTERNETBS_PASSWORD=your-password",
        "-e", "INTERNETBS_API_URL=https://api.internet.bs",
        "internetbs-mcp"
      ]
    }
  }
}

Build the image:

git clone https://github.com/uglyswap/internetbs-mcp.git
cd internetbs-mcp
docker build -t internetbs-mcp .

Where to put the config

Test Mode

Internet.bs provides a free sandbox — no account needed, no IP whitelisting:

{
  "mcpServers": {
    "internetbs": {
      "command": "npx",
      "args": ["-y", "internetbs-mcp"],
      "env": {
        "INTERNETBS_API_KEY": "testapi",
        "INTERNETBS_PASSWORD": "testpass",
        "INTERNETBS_API_URL": "https://testapi.internet.bs"
      }
    }
  }
}

The sandbox has limited data. Some operations will return test data only.

Usage Examples

Once configured, just ask in natural language:

Configuration Reference

Local mode (environment variables)

Remote mode (headers)

All 47 Tools

Domain Operations (11)

Transfer Operations (7)

DNS Records (4)

Nameserver Hosts (5)

URL Forwarding (4)

Email Forwarding (4)

Registrar Lock (3)

Private WHOIS (3)

Account (4)

Registrant Verification (2)

Security

• Local mode — Credentials never leave your machine. API calls go directly from your computer to Internet.bs over HTTPS.

• Remote mode — Credentials are passed via HTTPS headers on each request and forwarded to Internet.bs. The server does not log or persist them.

• IP whitelisting — Internet.bs requires your IP to be whitelisted, adding an extra layer of security.

• No database — The server is stateless. No user data, no sessions, no logs.

• Open source — Full code in this repository. Audit it yourself.

Important: Your Internet.bs API credentials can register and manage domains, which involves real money. Keep your API key and password secure. Never share them publicly.

Compatibility

Self-Hosting

Deploy on any server with a static IP (VPS, dedicated server, etc.).

With Docker

git clone https://github.com/uglyswap/internetbs-mcp.git
cd internetbs-mcp
docker build -t internetbs-mcp .
docker run -d --name internetbs-mcp -p 3000:3000 internetbs-mcp

With Node.js

git clone https://github.com/uglyswap/internetbs-mcp.git
cd internetbs-mcp
npm install
npm run build
npm start

As a Cloudflare Worker (advanced)

The repo includes a wrangler.toml and src/worker.ts for Cloudflare Workers deployment. However, Cloudflare Workers free tier uses shared/rotating IPs which are incompatible with Internet.bs IP whitelisting. This only works if:

• You have Cloudflare Enterprise with dedicated egress IPs, or

• You use the worker as a proxy behind a fixed-IP server

npx wrangler login
npm run deploy

Whitelisting your server's IP

1. Log into your Internet.bs account

2. Go to API settings

3. Create an API key whitelisted for your server's public IP

4. Use that API key in your deployment

If your server has multiple outbound IPs, whitelist the one used for HTTPS requests. Run curl ifconfig.me on the server to check.

Troubleshooting

"Missing credentials" error

Make sure your headers (remote) or env vars (local) are set correctly. The API key and password are both required.

"FAILURE" status in API responses

Usually means invalid credentials, IP not whitelisted, or the operation isn't supported. Check your Internet.bs account.

IP not authorized

Internet.bs requires IP whitelisting. Go to your account settings and add your machine's public IP. Run curl ifconfig.me to check your IP.

npx is slow on first run

npx downloads the package on first use (~25KB). Subsequent runs use the cache.

Connection timeout

The Internet.bs API can occasionally be slow. The default timeout is 25 seconds. If you experience timeouts, try again.

"Unknown tool" error

Run npx internetbs-mcp@latest to force update to the latest version.

Development

git clone https://github.com/uglyswap/internetbs-mcp.git
cd internetbs-mcp
npm install
npm run dev          # Local stdio server (hot reload)
npm run dev:worker   # Local Cloudflare Worker (http://localhost:8787)
npm run build        # Compile TypeScript
npm start            # Run compiled stdio version

Project structure

src/
  index.ts           # stdio entry point (local mode)
  worker.ts          # HTTP entry point (remote/self-hosted mode)
  client.ts          # Internet.bs API HTTP client
  types.ts           # TypeScript type definitions
  tools/
    domain.ts        # Domain management (11 tools)
    transfer.ts      # Domain transfers (7 tools)
    dns.ts           # DNS records (4 tools)
    host.ts          # Nameserver hosts (5 tools)
    forwarding.ts    # URL & email forwarding (8 tools)
    lock.ts          # Registrar lock (3 tools)
    whois.ts         # Private WHOIS (3 tools)
    account.ts       # Account operations (4 tools)
    verification.ts  # Registrant verification (2 tools)
    index.ts         # Aggregates all tools

Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/my-feature)

3. Commit your changes

4. Push and open a Pull Request

For bugs, open an issue.

Links

• Internet.bs — Domain registrar

• Internet.bs API Documentation — Official API docs

• Model Context Protocol — MCP specification

License

MIT — see LICENSE