legwork

# Legwork

<!-- mcp-name: io.github.kumarganduri/legwork -->

[![PyPI](https://img.shields.io/pypi/v/legwork-mcp)](https://pypi.org/project/legwork-mcp/)
[![CI](https://github.com/kumarganduri/legwork/actions/workflows/ci.yml/badge.svg)](https://github.com/kumarganduri/legwork/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

**Your AI finds the open-source tool it needs on GitHub. Legwork installs it in a sandbox.**

https://github.com/user-attachments/assets/9e9b80b5-99ff-4d21-b689-74655418f23d

<p align="center"><sub>A real run in Claude Desktop. The 25-second install is sped up; the malware repos' names are masked.</sub></p>

Add Legwork to Claude, Cursor, Codex, opencode or any [MCP](https://modelcontextprotocol.io)
client once. When you ask for something your AI has no tool for, it
searches GitHub, picks a repo, and asks you to approve installing it.
Legwork then checks the code for hidden payloads, builds a working tool for it in a
sandbox, tests it, and hands it over. In your home folder it can only read
the folders you allow.

```sh
claude mcp add legwork -- uvx legwork-mcp hub --allow-read ~/Downloads
```

Then just ask. Four to try first, all from the [public cache](cache/), so
they need no API key:

- *"Transcribe ~/Downloads/memo.m4a."* Any voice memo, mp3 or video;
  offline, many languages.
- *"Remove the background from ~/Downloads/photo.jpg."*
- *"Pull the tables out of ~/Downloads/report.pdf."*
- *"Make a QR code for https://github.com/kumarganduri/legwork."*

Your AI finds the tool ([faster-whisper](https://github.com/SYSTRAN/faster-whisper),
[rembg](https://github.com/danielgatis/rembg),
[pdfplumber](https://github.com/jsvine/pdfplumber),
[qrcode](https://github.com/lincolnloop/python-qrcode)), you approve the
install, and about a minute later it does the job. Files a tool makes are
copied to `~/Legwork/outputs/`. On macOS, the first time a tool reads
Downloads, macOS asks whether `uvx` may access it; allow it once. If
something doesn't work, `uvx legwork-mcp doctor` checks your setup. Or
build one tool yourself: `uvx legwork-mcp owner/repo` (a model key for repos
not in the cache).

## Why not just ask your AI to install it?

- **Most repos have no MCP server to install.** Your AI would have to write
  one on the spot, untested, every time. Legwork writes it once, proves it
  works with a self-test, and caches it so the next person doesn't pay for it.
- **Whatever your AI installs runs with full access to your machine:** your
  SSH keys, your files, your environment variables. That's how the two
  malware repos below would have got in. Legwork checks the code for
  obfuscated payloads first, and every tool it installs runs sandboxed: in your home folder it sees only
  the folders you grant.
- **It works across your tools:** the same install works in Claude Code,
  Claude Desktop, Cursor, opencode, Codex CLI, Goose and OpenClaw.

## What it did on real repos

On 2026-09-26 we ran Legwork against **the 10 most-starred AI repos created
on GitHub in the previous week**, taken exactly as search ranked them, with
nothing skipped for being hard:

| Outcome | Repos |
|---|---|
| ✅ Built a working MCP server | **3** — an npm CLI, a Python library, a Go binary |
| ↩️ Refused, with the right reason | **5** — two Android/macOS apps, a desktop app, a repo with no usage docs, a tool that needs its own API keys |
| 🛑 Blocked before install (malware) | **2** |

Two of those top-10 "AI tools", about 700 stars each and three days old
at the time, carried the same byte-identical obfuscated dropper under different
file names. Legwork's pre-install scan refused both in about a second.
Nothing from them was installed or run. Stars are not a trust signal.

The tripwire has to stay quiet on ordinary code too. Run over the 150
most-starred Python, JavaScript and TypeScript repos on GitHub
(2026-10-01), it blocks one: lodash, for a vendored 2009 debugging script
that really does run `eval(unescape(...))`.

Full write-up, including what failed along the way and what we fixed:
[docs/designs/legwork-trending-trial-2026-09-26.md](docs/designs/legwork-trending-trial-2026-09-26.md).

**A second, larger run** on the next 22 new trending repos, with two
models: **gpt-5 built 12 and refused 10 with reasons, with no crashes**;
OpenRouter's free Nemotron built 4. That run also caught two false malware
alarms and a gap where only published packages could be installed, both
fixed. [Write-up](docs/designs/legwork-trending-trial-2-2026-09-27.md).

## Let your AI find its own tools (hub)

`legwork hub` is one MCP server that gives your AI five tools: `find_tools`,
`install_tool`, `install_status`, `list_installed_tools` and `use_tool`.

```sh
claude mcp add legwork -- uvx legwork-mcp hub --allow-read ~/Downloads
```

For Claude Desktop or Cursor, add this to the MCP config (for Claude
Desktop, while the app is quit), with your own user name in the path: a
folder that doesn't exist stops the hub from starting.

```json
{ "mcpServers": { "legwork": { "command": "uvx",
  "args": ["legwork-mcp", "hub", "--allow-read", "/Users/you/Downloads"] } } }
```

For [opencode](https://opencode.ai), add this to `~/.config/opencode/opencode.json`.
opencode runs MCP tools without asking by default, so the `permission` line
is what makes it ask you before an install:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": { "legwork": { "type": "local",
    "command": ["uvx", "legwork-mcp", "hub", "--allow-read", "~/Downloads"] } },
  "permission": { "legwork_install_tool": "ask" }
}
```

- **You approve every install:** your client shows the repo and the
  folders it asks for.
- **The hub's flags are the ceiling.** An install can ask for the folders
  you allowed or less, never more, and no network unless you started the
  hub with `--allow-net`. Secret folders (`~/.ssh`, `~/.aws`, ...) are
  refused outright.
- **Installed tools appear by name** (`pdfplumber__extract_tables`), and
  `use_tool` works in clients that don't refresh their tool list. Installs
  are remembered across restarts.
- **Search results tell your AI what matters:** stars, license, how recently
  the repo was updated, whether it's in the Legwork cache, whether it
  already has an MCP server, and a warning on very new repos (the malware
  we caught was three days old). Descriptions are marked as untrusted text.

**37 tools are in the [public cache](cache/) and install in about a minute
with no API key**: speech-to-text, OCR, background removal, PDFs and
Office files, video, YouTube transcripts, charts, DuckDB and CSV tools, maths
and units, and linters and formatters. Each was built, reviewed by hand and
tried with a real call before it was added, and pins the version of the
package it wraps (its dependencies resolve at install). The cache a
release reads is the one tagged with that release, so a change to the cache
reaches you only with an upgrade. Others need a model key, and building takes 1–5 minutes. Put the key
in `~/.legwork.env` ([three lines](#model-providers), `chmod 600`) and the
hub reads it when it needs to build, so the key never goes in your MCP
config, where it would sit in plain text.

`legwork find "extract tables pdf"` runs the same search from your terminal.

- **Tools that use the internet** (YouTube transcripts and downloads, web
  pages) need the hub started with `--allow-net`; without it they install,
  then can't connect.
- **Files a tool makes** (a trimmed video, a chart, a QR code) are copied
  to `~/Legwork/outputs/<tool>/`, and the reply says where; images also
  come back inline. Your granted folders stay read-only, so a tool can't
  write next to your files. The copies are never executable, and on macOS
  they get the same quarantine flag as downloads. `--outputs DIR` puts
  them elsewhere, `--outputs off` turns copying off.
- **GitHub allows 10 searches a minute without a token**, and each
  `find_tools` uses 2 to 4. Cached tools still show up when GitHub says no.
  For 30 a minute, add `GITHUB_TOKEN=<a GitHub token with no scopes>` to
  `~/.legwork.env`.

### Other MCP clients

Legwork is a standard MCP server over stdio, so any client that runs local
MCP servers can use it. What differs is whether the client asks you before
it calls a tool. Legwork labels its tools (searching only reads; installing
acts), and the clients marked "asks" use those labels.

| Client | Tested | Add Legwork | Before an install |
|---|---|---|---|
| Claude Code | ✅ | `claude mcp add legwork -- uvx legwork-mcp hub --allow-read ~/Downloads` | asks |
| Claude Desktop | ✅ | JSON above | asks |
| Cursor | ✅ | JSON above | its default Auto-review mode lets an AI decide, and ran installs without asking in our test; to approve every install, set Settings → Agents → Approvals & Execution to Allowlist and leave `install_tool` off the list |
| opencode | ✅ 1.18 | JSON above | asks only with the `permission` line above |
| Codex CLI | ✅ 0.159 | `codex mcp add legwork -- uvx legwork-mcp hub --allow-read ~/Downloads` | asks |
| Goose | ✅ 1.52 | `goose session --with-extension "uvx legwork-mcp hub --allow-read ~/Downloads"` | asks with `GOOSE_MODE=smart_approve`; the default mode doesn't |
| OpenClaw | ✅ 2026.9 | `openclaw mcp add legwork --command uvx --arg legwork-mcp --arg hub --arg --allow-read --arg ~/Downloads` | its default full-permission mode doesn't ask |
| Gemini CLI, Cline, Zed, Continue, ... | not yet | the same command in the client's MCP config | check the client's settings |

In every client, the folders and network you start the hub with stay the
ceiling, whether or not the client asks.

**Faster starts:** `uvx` downloads Legwork on the first run, which can be
slower than some clients wait (Codex allows 10 seconds; add
`startup_timeout_sec = 60` under `[mcp_servers.legwork]` in
`~/.codex/config.toml`). Or install it once with `uv tool install
legwork-mcp` and use the full path that `which legwork` print