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:

Category	Tools	What you can do
Domains	11	Check availability, register, update, info, list, count, renew, restore, push, trade
Transfers	7	Initiate, retry, cancel, resend auth, history, approve/reject outgoing
DNS Records	4	Add, remove, update, list (A, AAAA, CNAME, MX, TXT, SRV, NS)
Nameservers	5	Create, info, update, delete, list glue records
URL Forwarding	4	Add, update, remove, list redirects
Email Forwarding	4	Add, update, remove, list email routes
Registrar Lock	3	Enable, disable, check status
Private WHOIS	3	Enable, disable, check status
Account	4	Balance, price list, configuration, total cost
Verification	2	Registrant email verification info & resend

---

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.

---

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

Client	Config file location
Claude Code	~/.claude.json → projects.<path>.mcpServers
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
Cursor	Settings > MCP Servers
Windsurf	~/.codeium/windsurf/mcp_config.json

---

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:

What you want to do	Example prompt
Check availability	"Is example.com available?"
Register a domain	"Register mysite.com with my contact info"
List domains	"List all my domains"
Domain info	"Show me the details for mysite.com"
DNS management	"Add an A record for www.mysite.com pointing to 93.184.216.34"
Email forwarding	"Forward info@mysite.com to me@gmail.com"
URL forwarding	"Redirect blog.mysite.com to mysite.com/blog"
Renew	"Renew mysite.com for 2 years"
Transfer	"Transfer example.org to my account, auth code is ABC123"
Account	"What's my account balance?"
Lock	"Enable registrar lock on mysite.com"
WHOIS privacy	"Enable private WHOIS on all my domains"

---

Configuration Reference

Local mode (environment variables)

Variable	Required	Description
INTERNETBS_API_KEY	Yes	Your Internet.bs API key
INTERNETBS_PASSWORD	Yes	Your Internet.bs API password
INTERNETBS_API_URL	No	API base URL. Default: https://testapi.internet.bs. Set to https://api.internet.bs for production

Remote mode (headers)

Header	Required	Description
X-InternetBS-Key	Yes	Your Internet.bs API key
X-InternetBS-Password	Yes	Your Internet.bs API password
X-InternetBS-URL	No	API base URL. Default: https://api.internet.bs. Use https://testapi.internet.bs for sandbox

---

All 47 Tools

Domain Operations (11)

Tool	Description
domain_check	Check if a domain is available for registration
domain_create	Register a new domain name
domain_update	Update domain contacts, nameservers, settings
domain_info	Get detailed domain information
domain_registry_status	Get domain registry status
domain_list	List all domains in the account
domain_count	Count domains by extension
domain_renew	Renew a domain registration
domain_restore	Restore a deleted domain in redemption period
domain_push	Push a domain to another Internet.bs account
domain_trade	Trade .eu/.fr domains (change registrant)

Transfer Operations (7)

Tool	Description
transfer_initiate	Initiate a domain transfer to your account
transfer_retry	Retry a failed domain transfer
transfer_cancel	Cancel a pending domain transfer
transfer_resend_auth_email	Resend transfer authorization email
transfer_history	Get transfer history for a domain
transfer_away_approve	Approve an outgoing domain transfer
transfer_away_reject	Reject an outgoing domain transfer

DNS Records (4)

Tool	Description
dns_record_add	Add a DNS record (A, AAAA, CNAME, MX, TXT, SRV, NS)
dns_record_remove	Remove a DNS record
dns_record_update	Update an existing DNS record
dns_record_list	List all DNS records for a domain

Nameserver Hosts (5)

Tool	Description
host_create	Create a nameserver host (glue record)
host_info	Get host information and IPs
host_update	Update host IP addresses
host_delete	Delete a nameserver host
host_list	List all hosts for a domain

URL Forwarding (4)

Tool	Description
url_forward_add	Add a URL forwarding rule
url_forward_update	Update a URL forwarding rule
url_forward_remove	Remove a URL forwarding rule
url_forward_list	List URL forwarding rules for a domain

Email Forwarding (4)

Tool	Description
email_forward_add	Add an email forwarding rule
email_forward_update	Update an email forwarding rule
email_forward_remove	Remove an email forwarding rule
email_forward_list	List email forwarding rules for a domain

Registrar Lock (3)

Tool	Description
registrar_lock_enable	Enable registrar lock (prevent unauthorized transfers)
registrar_lock_disable	Disable registrar lock
registrar_lock_status	Get current registrar lock status

Private WHOIS (3)

Tool	Description
private_whois_enable	Enable private WHOIS protection (FULL or PARTIAL)
private_whois_disable	Disable private WHOIS protection
private_whois_status	Get current private WHOIS status

Account (4)

Tool	Description
account_balance	Get account balance (supports multiple currencies)
account_price_list	Get pricing for all domain extensions
account_configuration	Get account configuration and settings
account_domains_total_cost	Get total annual cost of all domains

Registrant Verification (2)

Tool	Description
registrant_verification_info	Get registrant email verification status
registrant_verification_resend	Resend registrant verification email

---

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

Client	Local (npx)	Remote (URL)	Docker
Claude Code	Yes	Yes	Yes
Claude Desktop	Yes	Yes	Yes
Cursor	Yes	Yes	Yes
Windsurf	Yes	Yes	Yes
Zed	Yes	—	Yes
Any MCP client	Yes	Yes	Yes

---

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