Skip to main content
Glama
BorrowIP MCP Server

BorrowIP MCP Server

by wahyuzero

BorrowIP šŸ“”

Borrow mobile IP for AI agents — route traffic through your phone's cellular connection via SSH reverse tunnel.

Zero infrastructure. Uses existing SSH (port 22). Works with any MCP-compatible AI agent.

How it works

šŸ“± Phone (Termux)           šŸ–„ļø VPS                   šŸ¤– AI Agent
────────────────            ─────────                ──────────
borrowip connect            borrowip-mcp             Hermes/Claude
  BIP-xxxx@vps-ip             (auto-started)             ↓
    │                             │                  borrowip_fetch()
    ā”œā”€ā”€ SSH :22 ──────────────→  SSH :22                ↓
    │  pproxy :1080              SOCKS5 :10001       → cellular IP
    └── cellular ──→ internet ā†ā”€ā”€ā”˜

Related MCP server: @proxies-sx/mcp-server

Quick Start

1. VPS: Install & configure AI agent

git clone https://github.com/wahyuzero/borrowip
cd borrowip && pip install -e .

Add to your AI agent config (e.g. Hermes config.yaml):

mcp_servers:
  borrowip:
    command: borrowip-mcp

When AI agent starts, ask: "check borrowip status" → shows your pair code.

2. Phone (Termux): Install & connect

# Install
curl -sL https://raw.githubusercontent.com/wahyuzero/borrowip/main/scripts/install-termux.sh | bash

# Setup (first time only) — choose key or password auth
borrowip init

# Connect using pair code from VPS
borrowip connect BIP-xxxxxx@your-vps-ip

3. Done!

"Fetch https://example.com using borrowip key BIP-xxxxxx"

AI agent routes traffic through your phone's cellular IP automatically.

For AI Agents (LLM)

See LLM_GUIDE.md for a complete reference written for AI agents.

Quick summary of the 3-step workflow:

  1. borrowip_status() — check what's connected

  2. borrowip_get_proxy() — get the socks5:// URL

  3. borrowip_fetch(url) or browser_launch(proxy=<url>) — use the proxy

MCP Tools

Tool

Returns

Description

borrowip_status()

Text

Pair code + connected proxies with ports/IPs/alive status. Run first.

borrowip_get_proxy(key?)

socks5://127.0.0.1:PORT

Ready-to-use proxy URL. Use with browser tools.

borrowip_fetch(url, key?)

HTML/text

Fetch a URL through mobile proxy.

borrowip_health_check(key?)

ALIVE/DEAD/STALE

Fast 3s liveness test. Use when fetch fails.

borrowip_check_ip(key?)

IP address

Phone's external cellular IP.

borrowip_list_proxies()

Text

List all proxies with details.

Architecture

  • MCP Server (borrowip-mcp): Runs on VPS, auto-started by AI agent via stdio. Generates pair code, manages proxy connections.

  • Client (borrowip connect): Runs on Termux. Starts local SOCKS5 proxy (pproxy), creates SSH reverse tunnel, registers with pair code.

All traffic flows through SSH port 22 — no extra firewall rules.

Requirements

VPS: Python 3.10+, SSH on port 22, AI agent with MCP support (Hermes, Claude, Cursor, etc.)

Phone: Android + Termux, Python 3.10+, pproxy (pip install pproxy), SSH access to VPS (key or password)

Installation

VPS

git clone https://github.com/wahyuzero/borrowip
cd borrowip && pip install -e .

Termux

# Quick install
curl -sL https://raw.githubusercontent.com/wahyuzero/borrowip/main/scripts/install-termux.sh | bash

# Or manual
pkg install openssh python
pip install pproxy
git clone https://github.com/wahyuzero/borrowip
cd borrowip && pip install -e ".[client]"

Configuration

VPS (Hermes config.yaml)

mcp_servers:
  borrowip:
    command: borrowip-mcp

Termux (~/.borrowip.toml)

Created by borrowip init. Supports two auth methods:

Key auth:

[server]
host = "your-vps-ip"
user = "your-ssh-user"
ssh_key = "~/.ssh/id_ed25519"

Password auth:

[server]
host = "your-vps-ip"
user = "your-ssh-user"
ssh_password = "your-password"

Then just run borrowip connect (reads config automatically).

Auto-start (Termux)

# Install Termux:Boot from F-Droid
mkdir -p ~/.termux/boot/
echo 'borrowip connect &' > ~/.termux/boot/start-borrowip.sh
chmod +x ~/.termux/boot/start-borrowip.sh

Tunnel auto-reconnects on drop.

Security

  • SSH key or password auth

  • Pair code = identifier only; SSH credentials are the real auth

  • All traffic encrypted via SSH

  • SOCKS proxy bound to 127.0.0.1 only (not exposed to WiFi)

  • Pair code validated (prevents shell injection)

License

MIT

Available Tools

6 tools
borrowip_check_ipA

Check the external IP address of the mobile proxy.

Useful to verify the proxy is working and see which IP/cellular network is being used.

Args: key: Optional connection code. If omitted, uses first available proxy.

Inputs: key. Returns: result

borrowip_fetchA

Fetch a URL through the mobile proxy.

Use when a website blocks your server/VPS IP (Cloudflare, rate limits, geo-blocks). The request goes through the phone's cellular connection instead.

Args: url: The URL to fetch key: Optional connection code. If omitted, uses first available proxy.

Inputs: url (required), key. Returns: result

borrowip_get_proxyA

Get a ready-to-use SOCKS5 proxy URL.

Returns the proxy URL string directly (e.g. 'socks5://127.0.0.1:10002'). Use this URL with any tool that accepts a proxy parameter:

  • CloakBrowser: browser_launch(proxy='socks5://127.0.0.1:10002')

  • curl: curl --socks5-hostname 127.0.0.1:10002

  • requests: requests.get(url, proxies={'https': 'socks5h://127.0.0.1:10002'})

Args: key: Optional connection code (e.g. BIP-xxxxxx). If omitted, uses first available.

Inputs: key. Returns: result

borrowip_health_checkA

Quick liveness check — is the proxy tunnel actually working?

Tests if the SOCKS5 port is open AND can reach the internet. Much faster than borrowip_fetch (3s timeout vs 30s).

Args: key: Optional connection code. If omitted, checks first available proxy.

Inputs: key. Returns: result

borrowip_list_proxiesA

List all connected mobile proxies with details.

Returns one line per proxy: code, SOCKS5 URL, IP, age, alive status.

Inputs: no named parameters. Returns: result

borrowip_statusA

Check BorrowIP status. ALWAYS run this first.

Returns the pair code (for connecting a phone) and lists connected proxies with their SOCKS5 ports.

Example output: BorrowIP Status Pair code: BIP-ab12cd Proxies: 1 connected BIP-xw9su6 | socks5://127.0.0.1:10002 | IP: 140.213.141.84 | alive

If no proxies: tells you the exact Termux command to run.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a distinct purpose: checking IP, fetching, getting proxy URL, health check, listing, and status. No two tools perform the same function, making it clear for an agent which tool to use.

    Naming Consistency3/5

    All tools start with 'borrowip_', but the suffix patterns vary: verb_noun (check_ip, get_proxy, list_proxies), verb only (fetch), noun (status), and compound noun (health_check). This inconsistency could confuse an agent slightly.

    Tool Count5/5

    With 6 tools, the set is well-scoped for a proxy management server. Each tool serves a necessary function without being too few or too many.

    Completeness4/5

    The tools cover core proxy workflows: connecting (via status), listing, validating (check_ip, health_check), and using (fetch, get_proxy). Missing a dedicated disconnect tool is a minor gap but agents can work around it.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables agents to autonomously route traffic through real 4G/5G mobile and residential IPs by country, with tools to check live proxy stock, obtain ready-to-use proxy URLs, and monitor remaining data usage.
      51 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Routes AI agent HTTP requests through residential proxies to bypass anti-bot systems, geo-target by country/city, and maintain sticky sessions across multi-step workflows.
      15 npm
      1
      MIT