Skip to content
MCP server

Lupa — local file search for your Mac

Lets agents search a Mac's files by name and by text inside documents via the Lupa app

Runs locallyStatus and history
Install
Pricing
Free
Platforms
macOS, Windows, CLI
Runs
Locally
Version
0.3.1
Listing updated
3 days ago

About Lupa — local file search for your Mac

Lupa — local file search for your Mac is a free MCP server for files and documents. It runs locally on your machine and is started by your AI client.

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.

Install

Run in a terminal

claude mcp add lupa-mcp -- npx -y lupa-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "lupa-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "lupa-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "lupa-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "lupa-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

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

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Tools this server provides (2)

Taken from the project documentation; the running server may differ.

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.

What it does

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

Pricing

Free

Lupa is free in the Mac App Store; no API key or account

Prices change. Check lupa.kr before you buy.

Lupa — local file search for your Mac 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 to Lupa — local file search for your Mac

  1. Ha MCP

    MCP server

    MCP server for managing and automating Home Assistant from AI assistants

    Runs locally
    • 8 tools
    • Open source
    • 7.9K GitHub stars
    • Productivity
  2. Concord MCP

    MCP server

    Local-first MCP server for messaging and shared work-state between coding agents

    Runs locally
    • Freemium
    • 1.3K GitHub stars
    • Developer tools
  3. note1

    MCP server

    MCP server giving AI assistants search and summaries across your note1 meetings

    • 4 tools
    • Remote
    • Free trial
    • 1 GitHub star
    • Productivity
  4. ASTra

    MCP server

    Let agents read, edit, validate and undo Word .docx files with exact operations

    Runs locally
    • 5 tools
    • Freemium
    • Files and documents
  5. CalderFlow

    MCP server

    Turn notes or specs into editable flowcharts, timelines and funnels from an AI assistant

    • 10 tools
    • Remote
    • Free
    • Design and media
  6. CARTESIAN ECU

    MCP server

    Check and repair ECU and TCU flash-file checksums from Claude (Ultimate plan)

    Not checked yet
    • 5 tools
    • Remote
    • Paid
    • Files and documents