Zip1

🤖 AI Integration (MCP)

Use zip1.io directly from AI assistants like Claude through the Model Context Protocol (MCP). Create short links and read their stats using natural language commands.

🤖

AI-Powered URL Management

Talk to your URL shortener like you talk to an AI

• ✨ Natural language interface - no API syntax needed
• ⚡ Instant URL shortening from your AI assistant
• 📊 Get analytics on-demand with simple prompts
• 🔒 Create password-protected links conversationally

⚡ Quick Setup

For Claude Code (Recommended)

Claude Code supports HTTP MCP servers directly via CLI. Simply run:

claude mcp add --transport http zip1 https://zip1.io/mcp

Verify installation:

claude mcp list

✅ That's it! You can now use zip1.io directly from Claude Code.

For Claude Desktop

⚠️ Requires Proxy: Claude Desktop only supports stdio-based MCP servers, not HTTP servers. You'll need a local proxy to bridge the connection.

Option 1: Using mcp-client-cli (Recommended)

Install the MCP client CLI tool to bridge stdio to HTTP:

npm install -g @modelcontextprotocol/client-cli

Then edit your Claude Desktop config file:

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

Add this configuration:

{
  "mcpServers": {
    "zip1": {
      "command": "mcp-client",
      "args": ["https://zip1.io/mcp"]
    }
  }
}

Restart Claude Desktop and the zip1.io tools will be available.

Option 2: Custom Node.js Proxy

For advanced users, create a custom stdio-to-HTTP bridge script:

#!/usr/bin/env node
const https = require('https');
const readline = require('readline');

const MCP_URL = 'https://zip1.io/mcp';

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  terminal: false
});

rl.on('line', (line) => {
  const request = JSON.parse(line);

  const options = {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    }
  };

  const req = https.request(MCP_URL, options, (res) => {
    let data = '';
    res.on('data', (chunk) => data += chunk);
    res.on('end', () => {
      console.log(data);
    });
  });

  req.on('error', (error) => {
    console.error(JSON.stringify({
      jsonrpc: '2.0',
      id: request.id,
      error: { code: -32000, message: error.message }
    }));
  });

  req.write(JSON.stringify(request));
  req.end();
});

Make it executable and add to your Claude Desktop config:

chmod +x zip1-mcp-proxy.js

{
  "mcpServers": {
    "zip1": {
      "command": "node",
      "args": ["/path/to/zip1-mcp-proxy.js"]
    }
  }
}

⚙️ Server Configuration

The zip1.io MCP server is available as an HTTP endpoint that any MCP-compatible client can connect to.

Server Details

Configuration Item	Value
Server URL	https://zip1.io/mcp
Transport	HTTP (Streamable)
Protocol Version	MCP 2024-11-05
Message Format	JSON-RPC 2.0
Authentication	None (rate-limited)
Rate Limit	30 requests/minute per IP
Available Tools	4 (create_short_url, get_url_stats, validate_url, generate_short_code)

Using with Other MCP Clients

Any MCP-compatible client that supports HTTP transport can connect to zip1.io. Here are some examples:

Direct HTTP Requests (curl)

curl -X POST https://zip1.io/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

curl -X POST https://zip1.io/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "create_short_url",
      "arguments": {
        "url": "https://example.com",
        "alias": "my-link"
      }
    }
  }'

Python Client Example

import requests

MCP_URL = "https://zip1.io/mcp"

def call_mcp_tool(tool_name, arguments):
    payload = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": tool_name,
            "arguments": arguments
        }
    }

    response = requests.post(MCP_URL, json=payload)
    return response.json()

# Example usage
result = call_mcp_tool("create_short_url", {
    "url": "https://example.com",
    "alias": "mcp-docs"
})

print(result)

Self-Hosted Configuration

If you're running your own instance of zip1.io, configure clients to point to your instance:

claude mcp add --transport http zip1 https://your-domain.com/mcp

{
  "mcpServers": {
    "zip1-local": {
      "command": "mcp-client",
      "args": ["http://localhost:8000/mcp"]
    }
  }
}

💬 Example Conversations

Here are some natural language prompts you can use with Claude:

Creating Short URLs

"Shorten https://example.com for me"

Claude's Response:
✅ Short URL created: https://zip1.io/\[code\]
🔤 Generated code: [code]
🔗 Original URL: https://example.com
📊 View stats: https://zip1.io/stats/\[code\]

Custom Aliases & Passwords

"Create a short URL for https://example.com with alias 'docs' and password 'Preview@2026'"

Claude's Response:
✅ Short URL created: https://zip1.io/docs
📝 Custom alias: docs
🔒 Password protected: Yes
🔗 Original URL: https://example.com

Getting Analytics

"Show me the stats for short code 'docs', password 'Preview@2026'"

Claude's Response:
📊 Statistics for: https://zip1.io/docs
👆 Total clicks: 127
👤 Unique clicks: 89
🔒 Password protected: Yes
📅 Created: 2024-01-15T10:30:00

🌍 Top countries:
1. United States: 54 clicks
2. United Kingdom: 23 clicks
3. Canada: 18 clicks

URL Validation

"Can I shorten ftp://myserver.com/file.zip?"

Claude's Response:
❌ URL is invalid: Must include http:// or https:// protocol and a valid domain

🛠️ Available Tools

The zip1.io MCP server provides four tools that Claude can use:

Tool	Description	Example Usage
create_short_url	Create shortened URLs with optional custom aliases, passwords, max clicks, an expiry time (expiration_time) and a private note (description)	"Shorten this URL with alias 'mylink'"
get_url_stats	Retrieve click totals, unique visitors, countries, and the time of the last click. Anyone with the short link can see its stats. Password-protected links also need the password. Visitor IP addresses are stored to count unique visitors. They are never shown on the stats page or included in the export. Takes short_code and, when the link is password-protected, a password argument. Pass the password as that argument, never in a URL. A missing or wrong password returns an error and no link fields (no destination, no clicks). Too many failures returns HTTP 429 with Retry-After.	"Get stats for short code 'abc123', password 'Preview@2026'"
validate_url	Check if a URL is valid and can be shortened	"Can I shorten example.com?"
generate_short_code	Generate a random short code suggestion	"Generate a random short code"

description on create_short_url is an optional private note for your own integration, up to 100 characters. It is not shown on the link's public pages. Keep it free of personal data you wouldn't want stored. The create response returns it.

🔧 Technical Details

MCP Endpoint

GET /mcp

Returns server information, available tools, and configuration details.

Protocol Information

• Protocol Version: MCP 2024-11-05
• Transport: Streamable HTTP
• Message Format: JSON-RPC 2.0
• Rate Limit: 30 requests per minute per IP

Security

• All communication uses HTTPS encryption
• Passwords are hashed with bcrypt before storage
• get_url_stats does not return a password-protected link's destination or statistics until the password argument matches
• Rate limiting prevents abuse
• Same security infrastructure as the REST API

💡 Use Cases

📝 Content Creation

Generate short URLs while writing blog posts, documentation, or social media content without leaving your AI assistant.

📊 Quick Analytics

Ask for link performance during conversations. "How many clicks did my campaign link get?"

🔐 Secure Sharing

Create password-protected links on-the-fly when sharing sensitive information in team chats.

🎯 Campaign Management

Create custom-aliased URLs for marketing campaigns with natural language commands.

🔍 Troubleshooting

Rate limiting errors?

• The MCP endpoint has a limit of 30 requests per minute
• Wait a minute and try again

Tools not appearing in Claude Code?

• Ensure the MCP server URL is accessible
• Try visiting https://zip1.io/mcp in your browser
• Verify your MCP configuration with claude mcp list

📚 Resources & Documentation

• Official MCP Documentation - Learn more about the Model Context Protocol
• MCP Python SDK - Build your own MCP servers
• REST API Documentation - Traditional API access

Ready to Get Started?

Add zip1.io to Claude Code now and start shortening URLs with AI

claude mcp add --transport http zip1 https://zip1.io/mcp