# Lupa — local file search for your Mac

> Lupa — local file search for your Mac is a free MCP server for files and documents. Lets agents search a Mac's files by name and by text inside documents via the Lupa app. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Free
- **Platforms:** macOS, Windows, CLI
- **Website:** https://lupa.kr/agents.html
- **Repository:** https://github.com/under71/lupa-mcp
- **MCP Registry name:** io.github.under71/lupa-mcp
- **Categories:** files and documents, productivity
- **Listing updated:** 2026-11-15

## About

This server reads the local index built by Lupa, a macOS file search app, so an agent gets document contents without being given access to the disk. Searches run in about 30 ms entirely on the Mac with no network use, and cover PDF, Word, Excel, PowerPoint, plain text, Korean HWP and HWPX, and scanned PDFs read with OCR. Korean partial words and attached particles match, which the README contrasts with Spotlight.

There are two tools: lupa_search returns ranked paths with snippets, and lupa_read returns the text Lupa already extracted from a file, up to a character cap, which also works for formats an agent cannot parse. The query syntax supports name-only and content-only prefixes, folder filters, exclusions, exact phrases, wildcards, kind, size and date filters.

It must be installed through MCP rather than by shelling out to the command-line tool, because sandboxed agent shells such as Aside and Codex kill the App Store-signed binary with exit code 133 or 134. Lupa must be installed, with folders registered and indexed first. Every call is logged on your Mac so you can review what an agent searched. A Windows version of the app bundles its own MCP server, though without HWP body text or scanned-PDF OCR.

## Features

- **Content search:** Finds files by name and by text inside documents, including HWP and OCR'd scanned PDFs.
- **Read without opening:** lupa_read returns the indexed text of a file so agents can summarise formats they cannot parse.
- **Korean-aware matching:** Matches partial words inside compounds and attached particles.
- **Rich query syntax:** Supports name, content and folder prefixes, phrases, wildcards, and kind, size and date filters.
- **No disk access for agents:** The agent receives only indexed text from folders you registered.
- **Local audit log:** Each tool call is recorded in a log file on the Mac.

## Good for

- Find the contract that mentions a penalty clause
- Summarise a Korean HWP document an agent cannot open
- Search an Obsidian vault or synced cloud folder by content
- Look for large presentations modified this week
- Keep agent file lookups local without granting disk permissions

## Install

### Claude Code (Terminal)

```sh
claude mcp add lupa-mcp -- npx -y lupa-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "lupa-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "lupa-mcp"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "lupa-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "lupa-mcp"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "lupa-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "lupa-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "lupa-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "lupa-mcp"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "lupa-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "lupa-mcp"
      ]
    }
  }
}
```

## Tools

- `lupa_search`: Searches file names and document contents and returns ranked paths with snippets.
- `lupa_read`: Returns the indexed text of a file without opening it.

## FAQ

### Do I need the Lupa app?

Yes. The server reads the index Lupa builds, so install Lupa, add folders and let indexing finish first.

### How do I add it to Claude Code?

Run claude mcp add lupa -- npx -y lupa-mcp. Claude Desktop needs a login-shell wrapper because GUI apps do not inherit PATH.

### Why does the command-line tool fail in my agent?

Sandboxed shells block the App Store-signed binary with exit code 133 or 134, so register the MCP server instead.

### Does anything leave my computer?

The site says it uses no network and that agents receive only text Lupa has already indexed from registered folders.

### Is Lupa — local file search for your Mac free?

Yes. Lupa — local file search for your Mac is free to use.

### How do I add Lupa — local file search for your Mac to Claude Code?

Run this command in your terminal: claude mcp add lupa-mcp -- npx -y lupa-mcp

### What are the best alternatives to Lupa — local file search for your Mac?

The closest alternatives to Lupa — local file search for your Mac are Ha MCP, Concord MCP, note1, ASTra and CalderFlow.

## Alternatives

- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.
- [ASTra](https://ai-powered.com/mcp/astra): ASTra is a freemium MCP server for files and documents.
- [CalderFlow](https://ai-powered.com/mcp/calderflow): CalderFlow is a free MCP server for design and media.
- [CARTESIAN ECU](https://ai-powered.com/mcp/cartesian-ecu): CARTESIAN ECU is a paid MCP server for files and documents.
- [nicemails](https://ai-powered.com/mcp/nicemails): nicemails is a freemium MCP server for communication.
- [Invoices](https://ai-powered.com/mcp/invoices): Invoices is a paid MCP server for files and documents.

---
Source: https://ai-powered.com/mcp/lupa-local-file-search-for-your-mac-2
