# @klawfetch/mcp-server

**Your agent can't see the web from Tokyo. Now it can.**

KlawFetch is a geo-distributed HTTP proxy built for AI agents. Fetch web content from Frankfurt, Sydney, New York, or San Francisco — with one API call.

This MCP server gives any Claude, OpenAI, or MCP-compatible agent instant access to KlawFetch's full capabilities.

## Quick Start

```bash
# Install and run (needs Node.js 18+)
npx @klawfetch/mcp-server
```

Set your API key:
```bash
KLAWFETCH_API_KEY=your_key npx @klawfetch/mcp-server
```

Get an API key at [klawkeeper.xyz](https://klawkeeper.xyz)

## Add to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "klawfetch": {
      "command": "npx",
      "args": ["@klawfetch/mcp-server"],
      "env": {
        "KLAWFETCH_API_KEY": "your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. Your agent now has geo-distributed web access.

## Add to OpenAI / Other MCP Clients

Any MCP-compatible client works:

```json
{
  "mcpServers": {
    "klawfetch": {
      "command": "npx",
      "args": ["@klawfetch/mcp-server"],
      "env": {
        "KLAWFETCH_API_KEY": "your_key_here"
      }
    }
  }
}
```

## Tools

### `fetch_url`
Fetch any URL from a specific global region.

```
"Fetch https://example.com from Frankfurt"
"GET the homepage of news.ycombinator.com from Sydney"
"POST to https://api.example.com/data with body {key: value}"
```

**Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `url` | string | (required) | URL to fetch |
| `method` | string | `GET` | HTTP method |
| `headers` | object | — | Custom headers |
| `body` | any | — | Request body |
| `region` | string | auto | `eu-frankfurt`, `ap-sydney`, `us-west`, `us-east` |
| `follow_redirects` | boolean | `true` | Follow redirects |
| `timeout` | number | `30000` | Timeout in ms |
| `parse_json` | boolean | `false` | Parse response as JSON |

### `screenshot`
Capture a visual screenshot of any web page.

```
"Screenshot https://example.com at 1920x1080"
"Take a full-page screenshot of the dashboard"
```

### `scrape`
Extract structured data using CSS selectors.

```
"Scrape all h2 titles and .price elements from https://shop.example.com"
```

### `render`
Fetch with full JavaScript rendering (for SPAs/dynamic content).

```
"Render https://spa-app.com and wait for network idle"
```

### `list_regions`
Check which regions are online.

```
"What KlawFetch regions are available?"
```

## Direct API Usage (no MCP)

### curl

```bash
# Fetch a URL from Frankfurt
curl -X POST https://klawfetch.xyz/v1/fetch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "region": "eu-frankfurt"}'
```

### Python

```python
import requests

response = requests.post(
    "https://klawfetch.xyz/v1/fetch",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"url": "https://example.com", "region": "eu-frankfurt"}
)
data = response.json()
print(f"Status: {data['status']}, Body: {data['body'][:200]}")
```

### TypeScript / Node.js

```typescript
const res = await fetch("https://klawfetch.xyz/v1/fetch", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com",
    region: "eu-frankfurt",
  }),
});

const data = await res.json();
console.log(`Status: ${data.status}, Body: ${data.body.slice(0, 200)}`);
```

## Available Regions

| Region | ID | Location |
|--------|-------|----------|
| 🇩🇪 Frankfurt | `eu-frankfurt` | Germany |
| 🇦🇺 Sydney | `ap-sydney` | Australia |
| 🇺🇸 San Francisco | `us-west` | California |
| 🇺🇸 New York | `us-east` | New York |

Check real-time status: `GET https://klawfetch.xyz/v1/regions`

## Pricing

| Operation | Credits |
|-----------|---------|
| Fetch | 2 credits |
| Screenshot | 10 credits |
| Scrape | 5 credits |
| JS Render | 15 credits |

**~1,000 simple fetches for $1.** All regions included.

**Free tier:** 100 requests/day, no credit card required.

Get credits at [klawkeeper.xyz](https://klawkeeper.xyz). Pay with USDC, BTC, or card.

## Why KlawFetch?

**The problem:** Your AI agent runs in us-east-1. Every web request comes from the same IP block. Sites geo-restrict content, rate-limit your region, or serve different data based on location.

**The solution:** KlawFetch routes requests through VPS nodes in 4 global regions. Your agent sees the web the way a human in Frankfurt, Sydney, or San Francisco would.

- 🌍 **4 regions** — fetch from where your users are
- ⚡ **Sub-300ms** — optimized proxy, not a browser farm
- 🔒 **No IP leaking** — your agent's identity stays hidden
- 📸 **Screenshots + JS rendering** — see what humans see
- 🤖 **Built for agents** — MCP-native, API-first, pay-per-request

## Environment Variables

| Variable | Description |
|----------|-------------|
| `KLAWFETCH_API_KEY` | Your KlawKeeper API key (required) |
| `KLAWFETCH_API_BASE` | Custom API base URL (default: `https://klawfetch.xyz`) |

## License

MIT

## Links

- **API Docs:** [klawfetch.xyz](https://klawfetch.xyz)
- **Get API Key:** [klawkeeper.xyz](https://klawkeeper.xyz)
- **Full Stack:** [klawstack.xyz](https://klawstack.xyz)