# 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 🚀