lasso

<h1 align="center">Lasso</h1> > Claude Code's "full-interactive external grabber" - search, grab web pages, grab login pages, control desktop, all in one sentence. > Cowboy lasso, lasso any interface. <p align="center"> <img src="https://img.shields.io/npm/v/lasso-mcp"> <img src="https://img.shields.io/badge/license-MIT-green"> <img src="https://img.shields.io/badge/MCP-compatible-purple"> </p> **Install Lasso once, and then searching, grabbing web pages, grabbing login pages, and controlling desktop are all one sentence.** Every week, you need to search several times, grab a few articles, and click on the desktop app several times, but you don't want to install a separate tool for each task - here, install once and let Claude handle everything. Lasso is a twin star with [media-gen-mcp](https://github.com/wangdong233/media-gen-mcp) (image grabber): "all image operations go to one MCP" ↔ "all external interactions go to one MCP". <div align="center"> **English** | [简体中文](README.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) | [日本語](README.ja.md) | [Português](README.pt.md) | [Русский](README.ru.md) </div> ## Table of Contents - [What do you get from saying one sentence](#what-do-you-get-from-saying-one-sentence) - [💰 Cost list](#-cost-list) - [Get started in 60 seconds](#get-started-in-60-seconds) - [What can Lasso do for you](#what-can-lasso-do-for-you) - [Installation](#installation) - [Configuration details](#configuration-details) - [Privacy and security](#privacy-and-security) - [Troubleshooting](#troubleshooting) - [Who is it suitable for / not suitable for](#who-is-it-suitable-for--not-suitable-for) - [Support the author](#support-the-author) - [License](#license) --- ## What do you get from saying one sentence | What you say | What you get | |---|---| | "Search for the latest dynamics of rust async ecology" | Structured search results (if a website is temporarily down, it will automatically switch to the next one, you won't notice) | | "Grab the text on github.com homepage" | Clean text (automatically remove navigation / ads / redundant content, saving 30-70% of text) | | "Open my logged-in Jira to see the to-do list" | Logged-in page snapshot (reuse your local Chrome, 2FA you solve yourself) | | "This link is not available, find the archive" | Internet Archive's latest snapshot | | "List the files in the current Finder window" | Desktop window and control list (semantic tree, not screenshot) | | "Take a full-page screenshot" or "Save as PDF" | File path on disk (won't put a large image data into the conversation) | | "What third-party tracking does this page load?" | Resource list + tracking domain count | | "List all windows and web pages I can control now" | A unified list (web pages and desktop windows are all in it) | | "Turn off system dark mode" | Automatic click / input / shortcut key (with result verification, will confirm when done) | | "Directly take the return value of this JSON interface" | Raw bytes (fastest and most cost-effective) | | "This site has Cloudflare, I can't grab it" | Cloud-end Chrome anti-scraping (default off, you need to explicitly turn it on) | | "Is Lasso configured properly now?" | A health self-test report (tell you where it's not configured properly) | > You don't need to remember any capability names, just tell Claude what you want to do, and Claude will choose the most suitable way to complete it. --- ## 💰 Cost list Lasso itself is **completely free + MIT open source**. The cost of each capability is listed in the table: | Capability | Cost | Description | |---|---|---| | Lasso itself (MCP server + all core capabilities) | ✅ Free | MIT open source, free forever | | Search (Zhihu + Brave + Bing) | ✅ Free quota | Zhihu charges by token; Brave **2000 times/month free**, Bing **1000 times/month free** - you can use it without spending money. **If your machine has already configured `web-search-prime` Zhihu MCP? Lasso will automatically detect and reuse it, no need to configure ZHIPU_API_KEY separately** | | Grab public pages / screenshots / PDF / network audit / grab raw bytes | ✅ Free | Run locally, no key or payment required | | Grab logged-in pages (reuse local Chrome) | ✅ Free | Run locally, no key or payment required | | Control desktop (macOS / Windows / Linux) | ✅ Free | Local build and run, only need system authorization; **optional** Apple developer account $99/year for persistent authorization (no signature can also be used, but re-authorization each time) | | Cloud browser (browserbase / stagehand) | ⚠️ Paid, default off | Try before paying; **no configuration, no cost**, it's the only paid item for Lasso | > In summary: **as long as you don't turn on the cloud browser, Lasso is 0 cost** - search has a free quota for daily use, and other capabilities are completely free. --- ## Get started in 60 seconds ### 30 seconds | one-line access (zero configuration) ```bash claude mcp add lasso -- npx -y lasso-mcp ``` Restart Claude Code → input `/mcp` → see `lasso ✓ Connected` and you're done. **The installation command does not bring any key** - we'll talk about configuration later. ### 30 seconds | no configuration, can do these After installation, you can use it (this is **level 1: zero configuration**): - Grab text from any **public webpage** - **Take a full-page screenshot**, **save as PDF**, return file path - See **what third-party tracking a page loads** - Directly take **raw return** of JSON interface or file - Control macOS native app (Finder / Mail / System Settings, etc., need to check authorization in system settings) The first output - directly tell Claude: > "Grab the text on example.com, convert to markdown" ### Want more? Add configuration (level 2) - **Search** → run `lasso config init` to create `~/.lasso/config.json`, fill in a Zhihu key (see [configuration details](#configuration-details)) - **Grab logged-in pages** (Jira / GitHub private / company intranet) → run `lasso launch-chrome` once - **Control macOS desktop** → run `lasso doctor` once to guide authorization See [Key Configuration Guide](./doc/KEY-GUIDE.md) for how to apply for each key and free quota. --- ## What can Lasso do for you Grouped by what **you want to do**, not by tool name. Each group is a one-sentence input and output. ### Search > You: "Search for X" → structured search results Default use Zhihu (mainland China), can also add Brave, Bing for multi-source. **Any one of them is temporarily limited or down, automatically switch to the next one, you won't notice**. When a free quota is used up, it won't affect the overall use. ### Grab public pages (no login required) > You: "Grab example.com text" → clean text, three granularities optional Automatically remove navigation bars, ads, sidebars, and other redundant content, **saving 30-70% of text** (also more cost-effective). If you need to bring citation marks (suitable for research, feed RAG), you can switch with one sentence. ### Grab logged-in pages (with 2FA) > You: "See my Jira to-do list" → logged-in page snapshot Reuse your **local already logged-in Chrome** - you solve 2FA yourself, Lasso takes over subsequent grabbing. Supports private GitHub repositories, company intranet, paid subscription content, etc. > 🔴 **Red line**: Lasso **won't solve** 2FA / SMS verification code / CAPTCHA / email magic link for you. These must be manually solved in your local Chrome. ### Grab bytes directly (fastest and most cost-effective) > You: "GET this JSON interface" → raw bytes No need to render the entire page, directly use raw HTTP, **4 times faster and 4 times cheaper** than using a browser. Automatically identify content type (JSON / text / binary). ### Screenshot / archive > You: "Take a full-page screenshot" or "Save as PDF" → file path on disk All images and PDF are **saved locally, returning the path**, won't put a large image data into the conversation. ### See what a page loads > You: "What third-party tracking does this page load?" → resource list + tracking domain count Automatically identify all resources loaded by the page, aggregate by third-party domain, easy to see privacy risks and performance bottlenecks. ### Control desktop native app > You: "Turn off dark mode" or "Read the first email in Mail" → automatic operation (with verification) On macOS, can control Finder / Mail / Safari / Notes / System Settings, etc. **Windows / Linux can also be controlled** (see honest boundary below). Operation with result verification - when done, it will confirm. > **Honest boundary**: macOS has been verified in a real environment; Windows / Linux compilation and contract layer have passed self-test, but complete machine testing is still in progress. **No false claim of "complete verification on Win / Linux"**. ### Unified scheduling across web pages and desktop > You: "List all things I can control now" → a unified list Web pages and desktop windows share a list - you don't need to distinguish "this is in the browser" or "this is on the desktop", Claude will choose which one to operate on. ### Dead link rescue > You: "This link is 404" → Internet Archive's latest snapshot Go to the Internet Archive (Wayback Machine) to check the last archived version of the link. **Won't actively treat a live link as a dead link**, only check when you say "can't find it". ### Anti-scraping (default off) > You: "This site has Cloudflare, can't grab it" → cloud-end Chrome anti-scraping Default **completely off**. Only when you explicitly turn it on and configure a cloud-end browser key, it will be enabled. Ordinary pages don't need it. --- ## Installation **Prerequisites**: Node.js ≥ 20; Claude Code (or any MCP-supported client). ```bash # Claude Code (recommended) claude mcp add lasso -- npx -y lasso-mcp ``` Restart Claude Code → `/mcp` → `lasso ✓ Connected`. **This one-line command does not bring any key**, after installation, browse / screenshot / PDF / control desktop can be used immediately (except search, see [configuration details](#configuration-details)). **macOS users want to control desktop**: run `lasso doctor` once, follow the prompts to check `lasso-rust-helper` in "System Settings → Privacy & Security" to enable auxiliary functions and screen recording permissions. --- ## Configuration details **Zero configuration installation** - the above installation command can already run browse / fetch / screenshot / PDF / see third-party resources / control desktop. **Only search requires a key**. ### Check configuration by "what I want to do" | What you want to do | What to configure | Can be used immediately after configuration | |---|---|---| | Grab public pages / screenshots / PDF / see third-party resources / grab raw bytes / control desktop | **No configuration required** | Can be used immediately | | Search | A Zhihu key (free application) | Search main entrance | | Search is almost never down | Add Brave / Bing key (both have free quota) | Any one down, automatically switch, you won't notice | | Grab logged-in pages | Run `lasso launch-chrome` once | Reuse local Chrome login state | | Control macOS desktop | Run `lasso doctor` once | Control native app | | Grab sites with Cloudflare | Double confirmation + cloud-end key | Default off, you need to explicitly turn it on | Below are divided into four modules, each with the "shortest to run through" configuration. ### 1. Search (✅ Free · Free quota, one key starts, configure three families almost never down) **What can do**: Search for anything, return structured results (title, summary, link). **Do you need a key**: Yes - but if your machine has already configured Zhihu MCP `web-search-prime` (written in `~/.claude.json` `mcpServers`, type=http + Authorization), **Lasso will automatically detect and reuse its key as the search preferred source, no need to configure ZHIPU_API_KEY separately**. If the machine MCP is temporarily limited or fails, it will automatically degrade to Lasso's own configured key (fill in below). Run `lasso doctor` to see `#36 machine_search_mcp` is `pass` (host=open.bigmodel.cn) or `warn` (not detected) to know. > Zero configuration priority: machine MCP reuse → Lasso `ZHIPU_API_KEY` → Brave → Bing → `browse_headless` fallback. The previous one is down, automatically switch to the next one, you won't notice. **How to configure** (only needed when the machine has not configured Zhihu MCP / wants an independent key): ```bash lasso config init # Create ~/.lasso/config.json template ``` Open `~/.lasso/config.json`, fill in: ```json { "ZHIPU_API_KEY": "your Zhihu key" } ``` **Want to be more stable** (strongly recommended): add Brave, Bing, both have free quota. Any one of them is temporarily limited or down, automatically switch to the next one, you won't notice: ```json { "ZHIPU_API_KEY": "your Zhihu key", "BRAVE_API_KEYS": "bravekey1,bravekey2,bravekey3", "BING_API_KEYS": "bingkey1,bingkey2" } ``` > Multiple keys are separated by commas - N keys are拼成 N times free quota, automatically used in rotation. See [Key Configuration Guide · Search](./doc/KEY-GUIDE.md#a-search) for how to apply for a key, free quota, and multi-key rotation details. ### 2. Grab logged-in pages (✅ Free · No key, run one command) **What can do**: Grab your already logged-in pages - Jira to-do list, GitHub private repository, company intranet, paid subscription content. **Do you need a key**: No. **How to configure**: Run the following command once, it will automatically find your local Chrome, reuse your already logged-in sessions (2FA you have solved): ```bash lasso launch-chrome ``` After that, tell Claude "Open my logged-in Jira" will automatically connect. > 🔴 **Red line**: 2FA / SMS verification code / CAPTCHA / email magic link - Lasso won't solve it for you, must be manually solved in your local Chrome. See [Key Configuration Guide · Logged-in browsing](./doc/KEY-GUIDE.md#b-logged-in-browsing-command-line-configuration-no-key) for details. ### 3. Control desktop (✅ Free · No key, system authorization once) **What can do**: Control Finder, Mail, Safari, System Settings, etc. native apps on macOS / Windows / Linux (click, input, read window content, run shortcut keys). **Do you need a key**: No. **How to configure** (select one by system): - **macOS**: Run `lasso doctor` once, follow the prompts to check `lasso-rust-helper` in "System Settings → Privacy & Security" to enable auxiliary functions and screen recording permissions. `doctor` will guide you step by step. - **Windows**: When you tell Claude a desktop operation for the first time, the system will pop up an authorization window, click "Allow" (equivalent to macOS auxiliary functions). - **Linux**: Ensure the system has installed auxiliary function interfaces (most GNOME / MATE desktops have it by default, if not, `sudo apt install at-spi2-core`). > **Honest boundary**: macOS has been verified in a real environment; Windows / Linux compilation and contract layer have passed self-test, but complete machine testing is still in progress. **No false claim of "complete verification on Win / Linux"**. See [Key Configuration Guide · Desktop Control](./doc/KEY-GUIDE.md#c-desktop-control-system-authorization-no-key) for details. ### 4. Cloud-end anti-scraping (⚠️ Paid, default off · Double confirmation to turn on) **What can do**: Grab sites blocked by Cloudflare, heavy anti-scraping. **Do you need a key**: Yes, and **must be explicitly turned on** to enable. **How to configure**: Two conditions must be met simultaneously: 1. Main switch: `LASSO_ALLOW_CLOUD_BROWSER` set to `true` 2. At least one cloud-end key (browserbase or stagehand, choose one) Write into `~/.lasso/config.json`: ```json { "LASSO_ALLOW_CLOUD_BROWSER": true, "BROWSERBASE_API_KEY": "your browserbase key" } ``` > Default completely off - no configuration equals no capability. Ordinary pages don't need it, **only when you explicitly turn it on will it be enabled**. See [Key Configuration Guide · Cloud Browser](./doc/KEY-GUIDE.md#d-cloud-browser-anti-scraping-default-off-double-unlock) for how to apply for a cloud-end key and trial quota. <details> <summary><b>Advanced tuning (optional, ordinary users don't need to expand)</b></summary> Daily use **completely don't need to care** about the following. Only need in special scenarios, and most can be covered by `lasso config init` writing into `~/.lasso/config.json` or setting environment variables to override (environment variable priority higher than configuration file, convenient for temporary replacement): - Modify logged-in Chrome's debugging port (default `9222` occupied) - Change cache / status file storage location - Limit only use free search source - Allow company intranet / special proxy network segment - Add encryption password to logged-in cookie (not set then use macOS keychain) - Save search result snapshot (for regression testing) Complete variable list and default values see [Key Configuration Guide · Advanced Tuning](./doc/KEY-GUIDE.md#e-advanced-tuning-optional). **Surge / Clash etc. TUN proxy network (fake-ip) has built-in allowance, no need for extra configuration.** > **Backward compatibility**: If you previously installed with `claude mcp add -e KEY=VAL`, those environment variables **still take effect**, and will **override** configuration files. Configuration files are just a new friendly way, not abolishing the old method. </details> --- ## Privacy and security Your data is yours. - **Logged-in cookie never exported**, unless you explicitly agree and encrypt it to disk. Lasso won't secretly transmit your logged-in state to anywhere. - **Desktop operation logs only on local**, zero remote reporting. Lasso doesn't report your operations to any third party. - **Cloud browser default off**, must be **explicitly confirmed twice** (main switch + key) to enable. No configuration equals no capability. - **No 2FA / CAPTCHA / verification code solving** (red line). These must be manually solved in your local browser. - **No letting strangers touch your intranet service** - access intranet default rejected, protecting your internal services from being touched; Surge / Clash etc. TUN proxy network has built-in allowance, no need for extra configuration. - **Search result default no disk saving**, only when you actively enable recording mode will save a snapshot (for regression testing). --- ## Troubleshooting **If you encounter any issues, the first step is always `lasso doctor`.** It will self-check and tell you where the configuration is incorrect. | Phenomenon | What to Do | |---|---| | macOS desktop control not working | Check "System Settings → Privacy & Security → Accessibility / Screen Recording" and enable `lasso-rust-helper` ( `lasso doctor` will guide you ) | | Failed to capture logged-in page | Log in manually on your local Chrome browser once (also manually solve 2FA), then say "Open my logged-in X" | | Failed to save PDF | Say "Take a full-page screenshot" instead | | Search always yields no results | Check if the key has expired / quota is used up; configuring multiple providers (e.g., ZhiPu + Brave + Bing) can significantly reduce the failure rate | | Link cannot be opened | Say "This link is not found, try to find an archive" and check the Internet Archive | | Prompted to access internal network but denied | Confirm the URL is correct; TUN proxy network has been allowed by default, other internal networks need to be manually allowed | See the complete FAQ and debugging tips in [`doc/TROUBLESHOOTING.md`](./doc/TROUBLESHOOTING.md). --- ## Suitable for / Not Suitable for **Suitable for** - **Heavy Claude Code users** — Weekly searches, captures, and desktop control, no need to install a separate MCP for each task - **Researchers / Report writers / Data analysts** — Search, capture clean text, and revive dead links, all in one go - **RAG / Knowledge base builders** — Convert web pages to clean text with reference anchors, saving words and money - **Automation / DevOps practitioners** — Control macOS native apps, capture logged-in internal panels - **Frequent logged-in page capturers** — Reuse local Chrome session, no need to store accounts and passwords in configuration **Not suitable for** - **Those who don't use Claude Code or other MCP clients** — Lasso is an MCP service, requires an MCP client to drive it - **Those who only need a single capability and have a dedicated solution** — The all-in-one solution might be redundant for you - **Those who want to bypass 2FA / CAPTCHA** — Not possible, and not supported --- ## Support the Author If Lasso helps you, consider buying the author a cup of coffee ☕ <div align="center"> WeChat | Alipay :-: | :-: <img src="doc/support-wechat.jpg" height="200" alt="WeChat donation"> | <img src="doc/support-alipay.jpg" height="200" alt="Alipay donation"> </div> Or ⭐ [Star this repository](../../stargazers), [open an Issue](../../issues) / [submit a PR](../../pulls) — all encouragement and support for the author. --- ## More Documentation - For in-depth architecture, see [Functional Architecture](doc/08-media-interact-功能架构.md) - For version roadmap, see [Implementation Schedule](doc/09-media-interact-实施排期.md) - For key configuration, see [Key Configuration Guide](doc/KEY-GUIDE.md) ## License **MIT** © wangdong233. Desktop helper process and browser engine dependencies are MIT / Apache-2.0 licensed, allowing commercial use by enterprises. > For internal architecture, design principles, cross-platform boundaries, and development commands, see [ARCHITECTURE.md](./ARCHITECTURE.md) and [`doc/TROUBLESHOOTING.md`](./doc/TROUBLESHOOTING.md). <p align="center"> _{Built for everyone who'd rather <strong>say it</strong> than <strong>script it</strong>.}<br> _{Install once, and search / capture / logged-in capture / desktop control are all one-liners.} </p>