Content
# IPCONFIG MCP Server
[中文文档](README_zh.md) | English
A powerful IPCONFIG MCP (Model Context Protocol) server built on Cloudflare Workers, providing IP address lookup, geolocation, and network connectivity testing tools for AI assistants.
## 🌟 Features
- **IP Address Lookup** - Get current client's public IP address
- **IP Geolocation** - Detailed geographic location information for any IP address
- **Ping Connectivity Test** - Test network connectivity and latency to any host
- **CORS Support** - Full CORS support, accessible from any domain
- **High Performance** - Built on Cloudflare Workers edge computing platform
- **Standard Protocol** - Fully compatible with MCP protocol specifications
## 🔑 Getting Your API Key
Before configuring any MCP client, you need to obtain an API key from IPCONFIG:
### Step-by-Step Guide
1. **Create Account**
- Visit [IPCONFIG Console](https://ipconfig.com)
- Sign up for a free account or log in if you already have one
2. **Access API Keys Management**
- Navigate to the [API Keys page](https://ipconfig.com/docs/api/api-keys) in your console
- You'll see your API key management dashboard
3. **Create New API Key**
- Click the "Create New Key" button
- Enter a recognizable name for your API key (e.g., "MCP Client", "Claude Desktop")
- Click "Create"
4. **Save Your Key**
- ⚠️ **Critical**: Copy your API key immediately and store it securely
- The key will only be displayed once for security reasons
- If you lose it, you'll need to create a new one
### API Key Features
| Feature | Free Tier | Pro Tier |
|---------|-----------|----------|
| **Rate Limit** | 60 requests/min | 100 requests/sec |
| **Monthly Credits** | 1,000 | 10,000+ |
| **Get My IP** | ✅ Free | ✅ Free |
| **IP Location** | 1 credit/query | 1 credit/query |
| **Ping Test** | 1 credit/node | 1 credit/node |
For more details, visit the [API Key Management documentation](https://ipconfig.com/docs/api/api-keys).
## 🚀 Quick Start
### For Users
#### Cursor IDE Configuration (Recommended)
**One-Click Install**:
<a target="_blank" rel="noopener noreferrer" href="cursor://anysphere.cursor-deeplink/mcp/install?name=ipconfig&config=eyJjb21tYW5kIjogIm5weCIsICJhcmdzIjogWyJtY3AtcmVtb3RlIiwgImh0dHBzOi8vbWNwLmlwY29uZmlnLmNvbS9tY3AiXSwgImVudiI6IHsiSVBDT05GSUdfQVBJX0tFWSI6ICJ5b3VyLWFwaS1rZXktaGVyZSIsICJMQU5HVUFHRSI6ICJlbiJ9fQ==">
<img alt="One-Click Install to Cursor" src="https://cursor.com/deeplink/mcp-install-dark.svg">
</a>
**Manual Configuration**:
- **macOS**: `~/Library/Application Support/Cursor/mcp.json`
- **Windows**: `%APPDATA%\Cursor\mcp.json`
- **Linux**: `~/.config/Cursor/mcp.json`
```json
{
"mcpServers": {
"ipconfig": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.ipconfig.com/mcp"],
"env": {
"IPCONFIG_API_KEY": "your-api-key-here"
}
}
}
}
```
#### Claude Desktop Configuration
1. **Get API Key**: Follow the [API Key guide above](#-getting-your-api-key) to obtain your API key
2. **Configure Claude Desktop**:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
3. **Add Configuration**:
```json
{
"mcpServers": {
"ipconfig": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.ipconfig.com/mcp"],
"env": {
"IPCONFIG_API_KEY": "your-api-key-here"
}
}
}
}
```
4. **Restart Claude Desktop** and test: "What's my IP address?"
### For Developers
#### 1. Clone Repository
```bash
git clone https://github.com/your-username/ipconfig-mcp.git
cd ipconfig-mcp
```
#### 2. Install Dependencies
```bash
npm install
```
#### 3. Configure Environment
```bash
# Copy configuration file
cp wrangler.toml.example wrangler.toml
# Edit configuration (optional)
# - Modify project name
# - Configure custom domain
# - Set language preference
```
#### 4. Set API Key (Recommended)
```bash
wrangler secret put IPCONFIG_API_KEY
# Enter your API key (follow the API Key guide above to obtain one)
```
#### 5. Local Development
```bash
npm run dev
# Server will start at http://localhost:8787
```
#### 6. Deploy to Cloudflare
```bash
npm run deploy
```
## 📡 MCP Tools
### 1. get_my_ip - Get Current IP Address
Get the current client's public IP address and basic information.
**Parameters**:
- `format` (optional): `json` or `text`, default `json`
**Usage Examples**:
- "What's my IP address?"
- "Show me my current IP information"
- "Get my public IP in text format"
**Example Call**:
```json
{
"name": "get_my_ip",
"arguments": {"format": "json"}
}
```
**Sample Response**:
```json
{
"ip": "203.0.113.1",
"country": "United States",
"region": "California",
"city": "San Francisco",
"isp": "Example ISP",
"timezone": "America/Los_Angeles"
}
```
### 2. get_ip_location - IP Geolocation Lookup
Get detailed geographic location information for any IP address.
**Parameters**:
- `ip` (required): IP address (IPv4 or IPv6)
- `format` (optional): `json` or `text`, default `json`
**Usage Examples**:
- "Where is 8.8.8.8 located?"
- "Get location information for 1.1.1.1"
- "What's the geographic location of this IP: 208.67.222.222?"
**Example Call**:
```json
{
"name": "get_ip_location",
"arguments": {"ip": "8.8.8.8", "format": "json"}
}
```
**Sample Response**:
```json
{
"ip": "8.8.8.8",
"country": "United States",
"region": "California",
"city": "Mountain View",
"latitude": 37.4056,
"longitude": -122.0775,
"isp": "Google LLC",
"asn": "AS15169",
"timezone": "America/Los_Angeles"
}
```
### 3. ping_test - Network Connectivity Test
Test network connectivity and latency to any host from multiple global locations.
**Parameters**:
- `host` (required): hostname or IP address
- `count` (optional): number of pings, default 2, range 1-10
- `ipVersion` (optional): `ipv4` or `ipv6`, default `ipv4`
- `areas` (optional): test regions list, default major regions
**Usage Examples**:
- "Test connectivity to google.com"
- "Ping baidu.com from multiple locations"
- "Check network latency to my server at example.com"
**Example Call**:
```json
{
"name": "ping_test",
"arguments": {
"host": "google.com",
"count": 4,
"areas": ["california", "london", "tokyo"]
}
}
```
**Sample Response**:
```json
{
"host": "google.com",
"results": [
{
"area": "california",
"avg_latency": "12.5ms",
"packet_loss": "0%",
"status": "success"
},
{
"area": "london",
"avg_latency": "45.2ms",
"packet_loss": "0%",
"status": "success"
}
]
}
```
## 🔧 Configuration
### Environment Variables
Configure in `wrangler.toml`:
```toml
[vars]
MCP_SERVER_NAME = "IPCONFIG MCP Server"
MCP_SERVER_VERSION = "1.0.0"
LANGUAGE = "en" # or "zh" for Chinese
```
### Multilingual Support
- **Environment Variable**: `export LANGUAGE=zh`
- **Client Configuration**: Set `"LANGUAGE": "zh"` in MCP config
- **Request Parameter**: Include `"language": "zh"` in MCP requests
### API Key Configuration
- **Production**: Use `wrangler secret put IPCONFIG_API_KEY`
- **Client**: Set in MCP config `env` section
- **Get Key**: Follow the [API Key guide above](#-getting-your-api-key)
## 🧪 Testing
### Health Check
```bash
curl https://mcp.ipconfig.com/health
```
### MCP Tools Test
```bash
# Get tools list
curl -X POST https://mcp.ipconfig.com/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'
# Test tool call
curl -X POST https://mcp.ipconfig.com/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": {"name": "get_my_ip", "arguments": {"format": "json"}}
}'
```
### Using MCP Inspector
```bash
npx @modelcontextprotocol/inspector@latest
# Visit http://localhost:5173 in browser
# Connect to: https://mcp.ipconfig.com/mcp
```
## 📊 API Key Usage Limits
| API Key Type | Requests/Min | Requests/Day | Features |
|-------------|-------------|-------------|----------|
| Free | 100 | 1,000 | Basic features |
| Pro | 600 | 10,000 | Full features |
| Enterprise | 2,000 | 50,000 | Advanced features |
## 🏗️ Project Structure
```
ipconfig-mcp/
├── src/
│ ├── index.ts # Main entry file
│ ├── services/
│ │ └── ipconfig.ts # IPCONFIG API service
│ └── utils/
│ ├── cors.ts # CORS utilities
│ └── i18n.ts # Internationalization
├── wrangler.toml.example # Configuration template
├── cursor-mcp-config.json # Cursor IDE configuration
├── package.json # Project dependencies
├── tsconfig.json # TypeScript configuration
└── README.md # Project documentation
```
## 🔗 Links
- [IPCONFIG Website](https://ipconfig.com)
- [MCP Landing Page](https://ipconfig.com/mcp/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Cloudflare Workers](https://workers.cloudflare.com/)
## ❓ FAQ
**Q: How to verify configuration is working?**
A: Restart your client and ask the AI: "What's my IP address?" If it returns results, the configuration is successful.
**Q: What to do when encountering connection errors?**
A: Check network connection, verify API key is correct, and ensure configuration file format is valid.
**Q: What features are supported?**
A: Supports current IP lookup, IP geolocation, network connectivity testing, compatible with IPv4 and IPv6.
## 📄 License
MIT License
## 🤝 Contributing
Issues and Pull Requests are welcome!
---
**IPCONFIG MCP Server** - Empowering AI assistants with network diagnostic capabilities 🚀
