• Shorten
• API
• MCP
• Stats
• Report URL

🤖 AI Integration (MCP)

Use zip1.io directly from AI assistants like Claude through the Model Context Protocol (MCP). Shorten URLs, retrieve analytics, and manage links 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:

Terminal

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

Verify installation:

Terminal

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:

Terminal

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:

claude_desktop_config.json

{
  "mcpServers": {
    "zip1": {
      "command": "mcp-client",
      "args": ["http://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:

zip1-mcp-proxy.js

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

const MCP_URL = 'http://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:

Terminal

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	http://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)

List Available Tools

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

Create a Short URL

curl -X POST http://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

Python Script

import requests

MCP_URL = "http://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://github.com/anthropics/claude-mcp",
    "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 Code

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

Claude Desktop (with mcp-client)

{
  "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

Prompt

"Shorten https://github.com/anthropics/claude-mcp for me"

Claude's Response:
✅ Short URL created: https://zip1.io/Kj9dX2
🔤 Generated code: Kj9dX2
🔗 Original URL: https://github.com/anthropics/claude-mcp
📊 View stats: https://zip1.io/stats/Kj9dX2

Custom Aliases & Passwords

Prompt

"Create a short URL for https://docs.myapp.com with alias 'docs' and password 'team2024'"

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

Getting Analytics

Prompt

"Show me the stats for short code 'docs'"

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

Prompt

"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, and max clicks	"Shorten this URL with alias 'mylink'"
get_url_stats	Retrieve detailed analytics including clicks, countries, and timestamps	"Get stats for short code 'abc123'"
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"

🔧 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
• 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 http://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

Quick Setup