Ferret — Quick Start

Get started in 3 minutes. See API Reference for the full reference.

1. Start the server

git clone https://github.com/duan78/ferret.git
cd ferret
cargo build --release
./target/release/ferret serve

The REST API is available at http://localhost:9093.

systemd user services (recommended for long-running setups)

# Copy the unit files (shipped in the repo) if not already installed
cp ferret.service ferret-mcp.service ~/.config/systemd/user/

systemctl --user daemon-reload

# Start the REST API (port 9093)
systemctl --user start ferret.service
systemctl --user enable ferret.service

# Start the MCP server (port 9094)
systemctl --user start ferret-mcp.service
systemctl --user enable ferret-mcp.service

# Check status
systemctl --user status ferret.service ferret-mcp.service

2. Try it

# Search
curl "http://localhost:9093/search/bing?q=web+scraping"

# Multi-engine research
curl -X POST http://localhost:9093/research \
  -H "Content-Type: application/json" \
  -d '{"query": "AI developments 2026"}'

# Extract a URL
curl "http://localhost:9093/extract?q=https://example.com"

# Map a domain
curl "http://localhost:9093/map?q=https://example.com"

3. Python (3 lines)

import requests
r = requests.get("http://localhost:9093/search/bing?q=web+scraping")
print(r.json())

4. MCP quickstart (Cursor / Claude / OpenAI)

Pick your client and point it at http://localhost:9094/mcp:

Claude Code (one line):

claude mcp add ferret --transport http http://localhost:9094/mcp

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "ferret": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:9094/mcp"],
      "env": {}
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ferret-local": {
      "command": "/home/mini/ferret/target/release/ferret",
      "args": ["mcp", "--stdio"],
      "env": {}
    }
  }
}

OpenAI (GPT-4.1):

from openai import OpenAI
client = OpenAI()
resp = client.responses.create(
    model="gpt-4.1",
    tools=[{"type": "mcp", "server_url": "http://localhost:9094/mcp"}],
    input="Search the web for AI news",
)

Verify all 121 tools are exposed:

curl http://localhost:9094/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

See the MCP Server page for full configuration details.

5. Documentation