Filoo Server

npm version license

The official MCP server for filoo.app — an AI agent URL shortener with built-in click tracking. Plug this into Claude Desktop, Cursor, or any other Model Context Protocol client and your agent can shorten URLs, manage links, and read scan analytics through 8 first-class tools.

If you are looking for an "MCP server URL shortener", a "Claude URL shortener tool", a "Cursor link shortener", or a way to give an AI agent its own short link namespace, this is it.

What is filoo

filoo is an API-first URL shortener built for both humans and agents. Each link lives under a username (filoo.app/{username}/{slug}), comes with a QR code, and tracks clicks with country, device, referrer, and source breakdowns. The agents tier gives you 50,000 active links, 5,000 new links per day, unlimited usernames, and a 1,000 requests/minute API rate limit — designed so a fleet of agents can hammer the API without throttling.

Docs and pricing: https://filoo.app/api

Installation

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "filoo": {
      "command": "npx",
      "args": ["-y", "@filooapp/mcp-server"],
      "env": {
        "FILOO_API_KEY": "flo_live_xxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop. Your agent now has the 8 filoo tools.

Cursor

In Cursor settings → MCP, add a new server:

{
  "filoo": {
    "command": "npx",
    "args": ["-y", "@filooapp/mcp-server"],
    "env": { "FILOO_API_KEY": "flo_live_xxxxxxxxxxxx" }
  }
}

Generic MCP client (stdio)

FILOO_API_KEY=flo_live_xxxxxxxxxxxx npx -y @filooapp/mcp-server

The process speaks JSON-RPC over stdio per the MCP spec.

Local install

npm install -g @filooapp/mcp-server
FILOO_API_KEY=flo_live_xxxxxxxxxxxx mcp-server-filoo

Configuration

Env var	Required	Description
FILOO_API_KEY	yes	Your filoo API key, starts with flo_live_. Get one at https://filoo.app/dashboard/api (pro, agents, or lifetime tier).
FILOO_API_BASE	no	Override the API base URL. Defaults to https://filoo.app/api/v1.

The 8 tools

Each tool maps 1:1 to a filoo REST endpoint. The descriptions below are what the LLM reads when deciding which tool to call.

filoo_me

Get the authenticated user's account: tier, usernames, boost credits, and limits.

Example prompt: "What's my filoo plan and how many links can I still create?"

filoo_usage

Today's usage vs. quotas: links created today, API calls today, active link count vs. cap.

Example prompt: "How close am I to my filoo daily limit?"

filoo_list_usernames

List every username you own and which one is primary.

Example prompt: "List all my filoo usernames."

filoo_create_link

Create a new short link. Args: destination (required), slug?, username?, label?.

Example prompt: "Shorten https://example.com/very-long-launch-page under my 'agency' username with slug 'q4-launch'."

filoo_list_links

Cursor-paginated list of your links, newest first. Args: limit? (max 100), cursor?.

Example prompt: "Show me my last 20 filoo links."

filoo_get_link

Fetch one link by code. Args: code (form username:slug).

Example prompt: "What does filoo link agency:q4-launch point to?"

filoo_update_link

Repoint or rename a link without changing its short URL. Args: code, destination?, label?, active?.

Example prompt: "Point filoo link agency:q4-launch to the new landing page at https://example.com/launched."

filoo_delete_link

Permanently delete a short link. Args: code.

Example prompt: "Delete the filoo link agency:old-promo."

filoo_link_stats

Click totals, uniques, bots, top countries, and top sources for a link. Args: code.

Example prompt: "How is filoo link agency:q4-launch performing? Show top countries and sources."

Getting an API key

1. Sign up at https://filoo.app
2. Upgrade to the agents tier (50,000 links, 5,000/day, 1,000 req/min) — it's purpose-built for AI agent workloads. The pro and lifetime tiers also expose the API.
3. Go to https://filoo.app/dashboard/api and create a key. It starts with flo_live_.
4. Paste it into your MCP client config under FILOO_API_KEY.

Full API reference: https://filoo.app/api

Development

git clone https://github.com/filooapp/mcp-server
cd mcp-server
npm install
npm run build
FILOO_API_KEY=flo_live_xxx node dist/index.js

License

MIT © 2026 filoo