1001Proxy MCP Server

An MCP (Model Context Protocol) server that lets AI agents (Claude, GPT-4o, etc.) purchase and manage proxies from 1001Proxy directly within a conversation.

Setup

1. Get your API key

Log in to 1001proxy.io, go to Account, and copy your API key.

2. Install and build

cd mcp-server
npm install
npm run build

3. Environment variables

| Variable | Required | Default | Description | |-----------------|----------|--------------------------|------------------------------------| | PROXY_API_KEY | Yes | — | Your 1001Proxy API key | | PROXY_API_URL | No | https://1001proxy.io | Override for self-hosted instances |

Usage with Claude Desktop

Add the following to your claude_desktop_config.json (usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "1001proxy": {
      "command": "node",
      "args": ["/absolute/path/to/1001proxy/mcp-server/dist/index.js"],
      "env": {
        "PROXY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop after saving. You should see the 1001proxy tools available in the tool picker.

Usage with other MCP clients

The server speaks the MCP stdio transport protocol — launch it as a subprocess with PROXY_API_KEY in its environment:

PROXY_API_KEY=your-key node mcp-server/dist/index.js

Any MCP-compatible client (Cursor, Zed, custom agents) can connect using stdio transport.

Available tools

| Tool | Description | |------------------------|-----------------------------------------------------------------------------| | get_account | Check account info and current prepaid balance in USD | | list_proxy_types | Browse available proxy types with pricing guidance | | get_reference_data | Fetch countries, periods, tariffs, and operator IDs for a proxy type | | calculate_order | Get a price quote for an order without placing it | | create_order | Place an order and debit balance; supports idempotency keys | | list_orders | List orders with optional pagination, status, and type filters | | get_order | Get full details for a single order by ID | | get_proxies | Retrieve structured proxy credentials (IP, port, login, password) | | download_proxies | Download proxy list as plain text (txt or csv) | | extend_order | Renew an existing order for an additional period | | get_transactions | View balance transaction history (deposits, purchases, refunds) | | get_deposit_addresses| Get crypto deposit addresses to top up balance |

Example workflow

Below is a typical end-to-end session an AI agent would follow:

1. Check balance

get_account
→ { balance: "25.00", email: "[email protected]", ... }

2. Browse proxy types

list_proxy_types
→ [ { type: "ipv4", indicativePrice: "$0.30/IP", ... }, ... ]

3. Get reference data for the chosen type

get_reference_data { type: "ipv4" }
→ { countries: [...], periods: [...], tarifs: [...] }
  // Note countryId for US, periodId for 30 days

4. Calculate price before committing

calculate_order { type: "ipv4", countryId: 5, periodId: 3, quantity: 5, protocol: "https" }
→ { price: 1.50, currency: "USD", quantity: 5 }

5. Place the order

create_order {
  type: "ipv4",
  countryId: 5,
  periodId: 3,
  quantity: 5,
  protocol: "https",
  idempotency_key: "550e8400-e29b-41d4-a716-446655440000"
}
→ { ok: true, orderId: "clxyz...", charged: 1.50 }

6. Download proxies

download_proxies { order_id: "clxyz..." }
→ "1.2.3.4:10000\n5.6.7.8:10001\n..."

Proxy types quick reference

| Type | Best for | Billed by | |--------------|---------------------------------------------------|------------| | residential| Scraping, geo-bypass, ad verification | GB | | ipv4 | Automation, high-throughput tasks | IP/period | | ipv6 | Mass requests on IPv6-compatible targets | IP/period | | isp | Social media, e-commerce, long-running sessions | IP/period | | mobile | Platforms with aggressive anti-bot measures | IP/period |

Use get_reference_data with resident (not residential) when fetching reference data for residential proxies.

License

MIT