Lionscraper MCP + CLI + HTTP API Bridge

🚀 LionScraper MCP + CLI + HTTP API bridge

LionScraper is a browser extension that can collect various types of data from web pages. This repository provides a companion bridge between your tools and the extension in three ways: MCP, CLI, and HTTP API.

• Website: lionscraper.com
• npm: package lionscraper
• PyPI: project lionscraper

🚀 Quick Start

Prerequisites

1. Browser: Chrome or Edge (following the extension's supported browsers).
2. LionScraper extension: Install and enable it from the store.
   • Chrome: Chrome Web Store — LionScraper
   • Microsoft Edge: Edge Add-ons — LionScraper
3. Runtime:
   • Node.js 18+ for the npm package — Node.js
   • Python 3.10+ for the PyPI package — Python
4. For MCP: An AI app that supports MCP (e.g., Cursor, Trae).
5. For the HTTP API: The same browser, extension, and daemon as the CLI; refer to the package READMEs for paths and examples.

CLI Quick Start

lionscraper daemon
lionscraper ping
lionscraper scrape -u https://www.example.com

For full flags, multiple URLs, pagination, and HTTP API details, refer to packages/node/README.md / packages/python/README.md.

✨ Features

LionScraper is a browser extension capable of collecting lists, articles, links, images, and more from web pages. This repository offers a companion bridge between your tools and the extension in three ways:

• MCP (lionscraper-mcp): Connect an AI app (e.g., Cursor) so that the model can call scraping tools via stdio.
• CLI (lionscraper): Run daemon, scrape, ping, and more from a terminal on the same local HTTP/WebSocket port as the extension.
• HTTP API: When the daemon is running, call the same capabilities via loopback JSON HTTP (e.g., /v1/...) from scripts or any HTTP client—no MCP or CLI front - end required.

The real scraping logic runs in the extension; these packages connect and forward.

📦 Installation

Install (npm)

The package is published as lionscraper on npm.

npm install -g lionscraper

Without a global install, MCP can use npx; see the npx JSON examples under Add MCP in your AI app.

Install (pip)

The package is published as lionscraper on PyPI.

pip install -U lionscraper

A virtual environment is recommended, or use pip install -U --user lionscraper if you prefer not to install into the system interpreter.

Commands (both packages)

After pip install -U lionscraper, if lionscraper-mcp is not on your PATH, use python -m lionscraper with no extra arguments for MCP stdio (see packages/python/README.md).

PORT (default 13808) must match the extension bridge port in all modes.

💻 Usage Examples

Add MCP in your AI app

Examples assume lionscraper-mcp is on your PATH (from npm or pip). In MCP JSON, every env value is a string.

Minimal config (PORT defaults to 13808; must match the extension bridge port)

{
  "mcpServers": {
    "lionscraper": {
      "command": "lionscraper-mcp"
    }
  }
}

Full env example (omit keys you do not need)

{
  "mcpServers": {
    "lionscraper": {
      "command": "lionscraper-mcp",
      "env": {
        "PORT": "13808",
        "TIMEOUT": "120000",
        "LANG": "en-US",
        "TOKEN": "",
        "DAEMON": ""
      }
    }
  }
}

npx (no global install) — requires Node.js; the first run may download the package

The npm package name is lionscraper; the executable is lionscraper-mcp. Use command npx and pass lionscraper then lionscraper-mcp in args (after -y).

Minimal config (npx)

{
  "mcpServers": {
    "lionscraper": {
      "command": "npx",
      "args": ["-y", "lionscraper", "lionscraper-mcp"]
    }
  }
}

Full env example (npx)

{
  "mcpServers": {
    "lionscraper": {
      "command": "npx",
      "args": ["-y", "lionscraper", "lionscraper-mcp"],
      "env": {
        "PORT": "13808",
        "TIMEOUT": "120000",
        "LANG": "en-US",
        "TOKEN": "",
        "DAEMON": ""
      }
    }
  }
}

To pin a version, use e.g. "lionscraper@1.0.1" in place of "lionscraper" inside args.

• PORT: HTTP + WebSocket listen port; default 13808; must match the extension bridge port.
• TIMEOUT: ms to wait for a previous instance to release the port; default 120000; 0 forces takeover quickly.
• LANG: Tool descriptions and stderr language (en-US, zh-CN, or POSIX forms).
• TOKEN: Bearer token shared with the daemon; empty means no auth.
• DAEMON: Only 0 disables auto - starting lionscraper daemon from thin MCP.

Restart MCP or the host app after changing config.

Python: MCP via python -m

{
  "mcpServers": {
    "lionscraper": {
      "command": "python",
      "args": ["-m", "lionscraper"]
    }
  }
}

Use the same python you used to install the package (or python3 on some systems).

📚 Documentation

Match the port in the browser extension

1. Open LionScraper settings / options.
2. Set bridge port to the same value as PORT (e.g., 13808).
3. If needed, use Reconnect, reload the extension, or restart the browser.

Day - to - day use

1. Keep the extension enabled and target pages open as required.
2. Ask in natural language (e.g., check connection, scrape lists / article / emails / phones / links / images).
3. If you see “not connected” or timeouts, retry a connection check and confirm PORT matches.

FAQ

Extension not connected or scrape fails?

• Is the extension enabled?
• Does PORT in the AI app match the extension bridge port exactly?
• One bridge per machine is usually enough; duplicate MCP configs can conflict.

Seeing MCP tools in the client means everything works?

Not necessarily. Tools only prove AI → bridge; the extension must also register on the same port.

MCP Registry and directories

Official MCP Registry entries (both use server.json):

Publish outline (install the official CLI, see Quickstart):

1. Publish npm / PyPI at the version in each server.json.
2. In packages/node: mcp-publisher login github, then mcp-publisher publish.
3. In packages/python: mcp-publisher publish (login reused).

Third - party listings (e.g., Glama) have their own rules; Smithery targets public HTTPS/streaming setups rather than local stdio + npm/pip by default.

Third - party directory (Glama)

This project is listed on Glama (e.g., LionScraper on Glama). If the page shows cannot be installed or license not found, typical fixes are: add a root LICENSE (this repo includes LICENSE), add glama.json with maintainer GitHub usernames for org - owned repos (glama.json—edit maintainers if claim fails), claim the server on Glama, and optionally complete Glama’s Docker / release flow if you need their install and security/quality checks—official install remains npm install -g lionscraper and pip install -U lionscraper. See also the score / checklist page.

📄 License

MIT (same as the npm and PyPI packages).