Internet Names MCP Server

An MCP server for checking availability of domain names, social media handles, and subreddits. Returns clean JSON responses suitable for programmatic use.

Features

Domain names - Check availability via RDAP (free) or NameSilo API (free, but requires API key - responses include domain prices too)
Social media handles - Instagram, Twitter/X, Reddit, YouTube, TikTok, Twitch, Threads
Subreddits - Check if subreddit names are available on Reddit
Comprehensive search - Generate name combinations and check everything at once

Quick Start

1. Add to Claude Code (Recommended)

claude mcp add --scope user internet-names-mcp uvx internet-names-mcp

That's it! The server works immediately using RDAP for domain lookups.

2. Optional: Configure NameSilo API (for domain pricing)

Checking domain name availability works best if you configure a NameSilo API key. It's free and requires just a basic registration. Otherwise we fall back to using RDAP, which has some significant limitations (see below).

Set up your NameSilo API key

Create an account at namesilo.com (or log in)
Go to API Manager
Click Generate New API Key
Copy the key and run:

uvx internet-names-mcp --setup

You'll be prompted to paste your API key. On macOS, your API key is stored safely in your iCloud or login keychain as internet-names-mcp.namesilo. On other platforms, it's stored in ~/.config/internet-names-mcp/config.json.

Using --setup is the preferred method as it stores the key securely. Alternatively, you can set it via environment variable (see Manual Configuration below).

Manual Configuration

If you're not using Claude Code, or prefer to configure MCP servers manually, add this to your MCP client's configuration file (e.g., claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "internet-names-mcp": {
      "command": "uvx",
      "args": ["internet-names-mcp"]
    }
  }
}

To include a NameSilo API key via environment variable (if you haven't used --setup):

{
  "mcpServers": {
    "internet-names-mcp": {
      "command": "uvx",
      "args": ["internet-names-mcp"],
      "env": {
        "NAMESILO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Note: Using uvx internet-names-mcp --setup to store the API key is preferred over environment variables, as it uses secure storage (macOS Keychain) when available.

CLI Commands

uvx internet-names-mcp --setup         # Configure API keys interactively
uvx internet-names-mcp --show-config   # Show current configuration
uvx internet-names-mcp --version       # Show version
uvx internet-names-mcp --help          # Show help

Tools

get_supported_socials()

Returns list of supported social media platforms.

Response:

{
  "platforms": ["instagram", "twitter", "reddit", "youtube", "tiktok", "twitch", "threads", "subreddit"]
}

Note: subreddit is checked via check_subreddits(), not check_handles().

check_domains(names, tlds?, method?, only_report_available?)

Check domain name availability and pricing.

Parameters:

Name	Type	Default	Description
`names`	list[str]	required	Domain names or base names to check
`tlds`	list[str]	`["com", "io", "ai", "co", "app", "dev", "net", "org"]`	TLDs to check
`method`	str	`"auto"`	`"auto"`, `"rdap"`, or `"namesilo"`
`only_report_available`	bool	`false`	If true, omit unavailable domains from response

If a name contains a dot, it's treated as a full domain. Otherwise, it's combined with each TLD.

Response:

{
  "available": [
    {"domain": "myapp.com", "price": 17.29},
    {"domain": "myapp.io", "price": 34.99}
  ],
  "unavailable": ["myapp.ai"],
  "summary": {
    "cheapestAvailable": {"domain": "myapp.com", "price": 17.29},
    "shortestAvailable": {"domain": "myapp.io", "price": 34.99}
  }
}

check_handles(username, platforms?, only_report_available?)

Check social media handle availability across platforms.

Parameters:

Name	Type	Default	Description
`username`	str	required	The username/handle to check
`platforms`	list[str]	all platforms	Platforms to check
`only_report_available`	bool	`false`	If true, omit unavailable handles from response

Supported platforms: instagram, twitter, reddit, youtube, tiktok, twitch, threads

Note: Twitter/X checking uses a headless browser and takes ~4 seconds.

Response:

{
  "available": ["instagram", "tiktok", "youtube"],
  "unavailable": [
    {"platform": "twitter", "url": "https://x.com/myapp"},
    {"platform": "reddit", "url": "https://reddit.com/user/myapp"}
  ]
}

check_subreddits(names, only_report_available?)

Check subreddit name availability on Reddit.

Parameters:

Name	Type	Default	Description
`names`	list[str]	required	Subreddit names to check (with or without r/ prefix)
`only_report_available`	bool	`false`	If true, omit unavailable subreddits from response

Response:

{
  "available": ["mynewsubreddit"],
  "unavailable": [
    {"name": "programming", "subscribers": 6835000},
    {"name": "privatesubreddit", "note": "private"}
  ]
}

check_everything(components, tlds?, platforms?, method?, require_all_tlds_available?, only_report_available?, also_include_hyphens?)

Comprehensive check across domains and social media. Generates name combinations from components, checks domains first (fast), then checks social handles for names that pass the domain check.

Parameters:

Name	Type	Default	Description
`components`	list[str]	required	Name components to combine (e.g., `["red", "sweater"]`)
`tlds`	list[str]	`["com", "net", "org", "io", "ai"]`	TLDs to check
`platforms`	list[str]	all platforms	Social platforms to check
`method`	str	`"auto"`	`"auto"`, `"rdap"`, or `"namesilo"`
`require_all_tlds_available`	bool	`false`	If true, name must be available in ALL TLDs to qualify for handle checking
`only_report_available`	bool	`false`	If true, omit unavailable items from response
`also_include_hyphens`	bool	`false`	If true, also check hyphenated versions

Name Generation: From components ["red", "sweater"], generates:

Single components: red, sweater
Concatenations: redsweater, sweaterred

Response:

{
  "available_domains": [
    {"domain": "redsweater.com", "price": 17.29},
    {"domain": "redsweater.io", "price": 34.99}
  ],
  "domain_successful_basenames": ["redsweater", "sweaterred"],
  "available_handles": {
    "redsweater": ["instagram", "twitter", "youtube"],
    "sweaterred": ["instagram", "tiktok"]
  },
  "unavailable_handles": {
    "redsweater": [{"platform": "reddit", "url": "..."}]
  },
  "summary": {
    "fully_available": ["sweaterred"],
    "cheapest_domain": {"domain": "redsweater.com", "price": 17.29}
  }
}

The fully_available list contains names that are available on ALL checked platforms.

Domain Lookup Methods

Method	Description	Pricing	Speed
`auto`	Uses NameSilo if API key configured, otherwise RDAP	With NameSilo	Fast
`rdap`	Direct registry queries via IANA bootstrap	No	Fast
`namesilo`	NameSilo API (requires API key)	Yes	Fast

RDAP Limitations

RDAP is free and requires no API key, but has some limitations:

TLD coverage - Not all top level domains (TLDs) have RDAP servers. Queries for unsupported TLDs will fail. RDAP works for .com, .net, .org, .app, .ai and more. See deployment.rdap.org for an up-to-date list (look for 'Yes' in the 'RDAP' column).
No pricing - RDAP only reports availability, not the cost to register the domain.
False positives - A domain may appear available via RDAP but actually be reserved or considered "premium" by registrars, making it effectively unavailable or prohibitively expensive to purchase.

For reliable results with pricing, configure a NameSilo API key.

Configuration

API key storage:

macOS: Keychain (as internet-names-mcp.namesilo)
Linux: ~/.config/internet-names-mcp/config.json
Windows: %APPDATA%/internet-names-mcp/config.json

API key lookup order (first match wins):

macOS Keychain (on macOS only)
Environment variable (NAMESILO_API_KEY)
Config file (fallback)

Development

Local Setup

The devsetup.sh script handles virtual environment creation and dependency installation:

git clone <repo-url> InternetNamesMCP
cd InternetNamesMCP
source devsetup.sh          # Creates .venv, activates it, installs dependencies
playwright install chromium # Required for Twitter/X handle checking

Options:

source devsetup.sh - Set up environment (default)
source devsetup.sh --clean - Delete venv and caches
source devsetup.sh --clean --setup - Clean rebuild

API Key Configuration (Development)

When running from source, use the module directly instead of uvx:

source devsetup.sh  # Activate environment first

python -m internet_names_mcp --setup       # Configure API keys interactively
python -m internet_names_mcp --show-config # Show current configuration and key source
python -m internet_names_mcp --version     # Show version

Running Tests

source devsetup.sh  # Activate environment first

# Main test suites
python test_server.py         # Full test suite - offline validation + online API tests
python test_mcp_interface.py  # Tests via MCP protocol (stdio transport)
python test_rdap_client.py    # Async RDAP client, rate limiter, batch queries

# Comparison/diagnostic tests
python test_methods.py        # Compare RDAP vs NameSilo results for discrepancies
python test_rdap.py           # Quick RDAP-only domain check

Test File	Description
`test_server.py`	Main test suite covering all MCP tools, edge cases, and API calls
`test_mcp_interface.py`	Tests the server through actual MCP protocol via stdio
`test_rdap_client.py`	Tests async RDAP client, rate limiting, and batch queries
`test_methods.py`	Compares RDAP vs NameSilo to detect availability discrepancies
`test_rdap.py`	Simple RDAP-only test for quick domain availability checks

Interactive Testing

Use MCP Inspector for interactive debugging with a web UI:

npx @modelcontextprotocol/inspector .venv/bin/python -m internet_names_mcp

Project Structure

├── src/internet_names_mcp/
│   ├── __init__.py       # CLI entry point
│   ├── __main__.py       # Module runner
│   ├── server.py         # MCP server
│   ├── config.py         # Configuration management
│   ├── rdap_bootstrap.py # RDAP bootstrap cache
│   └── rdap_client.py    # Async RDAP client
├── pyproject.toml       # Package configuration
└── README.md

Data Files

RDAP Bootstrap Cache - Maps TLDs to their authoritative RDAP servers (auto-downloaded from IANA):

macOS/Linux: ~/.cache/internet-names-mcp/rdap_bootstrap.json
Windows: %APPDATA%/internet-names-mcp/rdap_bootstrap.json

The cache is automatically refreshed when expired (default 24h TTL from IANA's Cache-Control headers).

Troubleshooting

"sherlock not found"

Sherlock is installed automatically as a dependency. If you see this error, reinstall:

uvx --reinstall internet-names-mcp

"playwright not installed" or Chromium errors

Install Playwright browser:

playwright install chromium

Or with uvx:

uvx --from playwright install chromium

Twitter checks fail or timeout

Twitter/X checks use a headless browser which can be slow or blocked. If checks consistently fail, Twitter may be rate-limiting or blocking automated access.

Copyright

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
src/internet_names_mcp		src/internet_names_mcp
.gitignore		.gitignore
README.md		README.md
ROADMAP.md		ROADMAP.md
devsetup.sh		devsetup.sh
license.md		license.md
publish.py		publish.py
pyproject.toml		pyproject.toml
test_mcp_interface.py		test_mcp_interface.py
test_methods.py		test_methods.py
test_rdap.py		test_rdap.py
test_rdap_client.py		test_rdap_client.py
test_server.py		test_server.py
test_socials.py		test_socials.py

Folders and files

Latest commit

History

Repository files navigation

Internet Names MCP Server

Features

Quick Start

1. Add to Claude Code (Recommended)

2. Optional: Configure NameSilo API (for domain pricing)

Set up your NameSilo API key

Manual Configuration

CLI Commands

Tools

get_supported_socials()

check_domains(names, tlds?, method?, only_report_available?)

check_handles(username, platforms?, only_report_available?)

check_subreddits(names, only_report_available?)

check_everything(components, tlds?, platforms?, method?, require_all_tlds_available?, only_report_available?, also_include_hyphens?)

Domain Lookup Methods

RDAP Limitations

Configuration

Development

Local Setup

API Key Configuration (Development)

Running Tests

Interactive Testing

Project Structure

Data Files

Troubleshooting

"sherlock not found"

"playwright not installed" or Chromium errors

Twitter checks fail or timeout

Copyright

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages