Once connected, Claude Desktop can search your StashBase projects, including the extracted text of PDFs, DOCX files and images, and read or edit files inside those projects. Nothing outside them is reachable.

Still deciding how Claude should reach your files at all — Cowork, Projects uploads, an MCP server, or an indexed library? Start with the comparison: how to give Claude access to your local files.

What Claude gets

  • list_projects: your StashBase projects and their search setup.
  • search_project: keyword and (if configured) meaning-based search in one project, optionally scoped to a path prefix.
  • reindex: pick up file changes made outside StashBase.
  • create_project: start a new project folder.
  • Bounded file helpers: list_directory, read_file, write_file, edit_file, move_file, delete_file, inside your projects only. MCP access is deliberately not a general filesystem interface.

Prerequisites

  • StashBase installed with at least one project.
  • The StashBase app running — the MCP server lives in the app.
  • Claude Desktop installed.

Copy the config from StashBase

  1. In StashBase, open Settings → Advanced → External apps (MCP).
  2. Copy the configuration from the Command tab. It already points at the packaged command for your machine.
  3. Paste it into Claude Desktop’s config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows), merging with any mcpServers entries already there.
  4. Restart Claude Desktop.

StashBase does not write external clients’ configuration for you; only the in-app Chat runtimes are wired automatically.

Manual setup

If you would rather write the file by hand, the packaged MCP command is generated at:

~/.stashbase/bin/stashbase-mcp                    # macOS / Linux
%USERPROFILE%\.stashbase\bin\stashbase-mcp.cmd    # Windows

Add it to Claude Desktop’s config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "stashbase": {
      "command": "/Users/YOUR_USER/.stashbase/bin/stashbase-mcp"
    }
  }
}

Restart Claude Desktop after changing its MCP configuration.

Verify it works

Ask Claude something like “use stashbase to search my project for …”. You should see it call search_project. New MCP servers appear in Claude Desktop’s tools menu after a restart.

Troubleshooting

  • Tools don’t appear — restart Claude Desktop; MCP config is read at startup.
  • Search returns nothing — check the StashBase app is running, and that the project you expect is open in StashBase. In-app search readiness also applies here: files still being prepared aren’t searchable yet.
  • Meaning-based queries fall back to keyword behaviour — search by meaning needs your own OpenAI or OpenRouter key under Settings → Advanced → Search by Meaning; Default Agent credits do not cover it. Keyword search works without a key.
  • Config JSON errors — Claude Desktop silently ignores invalid JSON; validate the file if the server never shows up.

For URL-based clients, Docker access, ports, and token rotation, see Advanced MCP configuration in the main repository. To use Claude Code instead, the short version is:

claude mcp add stashbase -- ~/.stashbase/bin/stashbase-mcp

Frequently asked questions

Does StashBase need to be running for Claude Desktop to use it?

Yes. The MCP server lives in the StashBase app, so the app has to be open while Claude Desktop searches or reads your project.

Can Claude Desktop see my whole computer through StashBase?

No. Claude Desktop reaches only the StashBase project you select and authorize, and the file tools work inside it and nowhere else. The MCP server is not a general filesystem interface.

Can Claude Desktop read my PDFs and scans through StashBase?

Yes. StashBase serves the text it prepared from PDFs, DOCX files and images, so Claude can search it and read the prepared text of a PDF or DOCX file instead of the raw file. Audio and video are not transcribed.

Do I need search by meaning set up to use StashBase from Claude Desktop?

No. Keyword search works without any key. If you have added your own OpenAI or OpenRouter key in StashBase, searches from Claude Desktop can also match by meaning.