Use Pinggy with AI Agents

Pinggy plugs into AI coding agents two ways. Install the skill to give an agent ready-made instructions for using Pinggy, or add the MCP server to let the agent create and manage tunnels directly through tool calls. Both can be installed together.

npx skills add https://pinggy.io

If unsure, start with the skill. Add the MCP server when the agent should run tunnels on its own.

Install the Pinggy skill

Skills are packaged instructions an agent loads on demand. The Pinggy skill is published under the Agent Skills standard at https://pinggy.io/.well-known/skills/. The skills CLI fetches the manifest, downloads the skill files, and drops them into the agent’s skills directory. The only prerequisite is Node.js.

npx (any agent)

npx skills add https://pinggy.io

Claude Code and Cursor

The same command works. The CLI detects the agent and writes the skill to its skills directory, for example ~/.claude/skills/pinggy/ for Claude Code.

Manual

Download the files listed in https://pinggy.io/.well-known/skills/index.json from https://pinggy.io/.well-known/skills/pinggy/ and place SKILL.md (with the scripts/ and references/ folders) in the agent’s skills directory.

Install the Pinggy MCP server

The MCP (Model Context Protocol) server lets agents like Claude Code, Claude Desktop, and Cursor create and control Pinggy tunnels in natural language.

Prerequisites: Python 3.10 or newer and uv. Install uv with:

curl -LsSf https://astral.sh/uv/install.sh | sh

Nothing is installed globally. Each client runs uvx, which fetches and runs pinggy-mcp on demand.

Claude Code

claude mcp add pinggy-mcp -- uvx --from git+https://github.com/Pinggy-io/pinggy_mcp.git pinggy-mcp

Verify it registered:

claude mcp list

Claude Desktop

Edit the Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pinggy-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Pinggy-io/pinggy_mcp.git",
        "pinggy-mcp"
      ]
    }
  }
}

Restart Claude Desktop. The pinggy server appears in the MCP indicator below the input box.

Cursor

Edit ~/.cursor/mcp.json for a global config, or .cursor/mcp.json in a project root for a per-project config:

{
  "mcpServers": {
    "pinggy-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Pinggy-io/pinggy_mcp.git",
        "pinggy-mcp"
      ]
    }
  }
}

VS Code

Edit ~/.vscode/mcp.json (global) or .vscode/mcp.json in a project root:

{
  "servers": {
    "pinggy-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Pinggy-io/pinggy_mcp.git",
        "pinggy-mcp"
      ]
    }
  }
}

Reload the window (Developer: Reload Window from the command palette).

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "pinggy-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Pinggy-io/pinggy_mcp.git",
        "pinggy-mcp"
      ]
    }
  }
}

Restart Windsurf after saving.

What you can do

Once the MCP server is installed, ask the agent in plain language:

• “Expose my dev server on port 3000.”
• “Open a TCP tunnel to localhost:22.”
• “Share my ~/Downloads folder over the internet.”
• “Log in to Pinggy.”
• “List my active tunnels.”
• “Only allow traffic from 1.2.3.4 to my tunnel.”
• “Stop the tunnel.”

Plain-text docs for LLMs

Every Pinggy doc page is also published as Markdown at the same path with an index.md suffix, for example https://pinggy.io/docs/cli/index.md. The site also serves a single overview at https://pinggy.io/llms.txt that an agent can fetch to learn how Pinggy works.

See also

• Pinggy CLI
• Node.js SDK and Python SDK
• MCP server source and issues: github.com/Pinggy-io/pinggy_mcp (early and experimental, feedback welcome)