DocsAgent: a local-first document index that speaks MCP to your AI agent

The problem DocsAgent targets: agents that cannot read your desktop

An MCP-capable agent can call tools, but it has no idea what is in your home directory. The usual workaround is to copy documents into a hosted service or paste them into a chat window, which is exactly what people handling contracts, research papers or internal decks do not want to do. DocsAgent positions itself as the missing local layer: a CLI that parses and indexes files on your hardware, plus an MCP server that exposes that index as tools the agent can call. The README frames the audience as anyone with a private document library of roughly 1,000 files or more, and it names OpenClaw, Claude Code and Cursor as the agent platforms it integrates with. The Zotero and Obsidian add-ons, papersgpt-for-zotero and docsagent-for-obsidian, show the same pattern applied to a reference manager and a notes vault.

How the engine is put together: a CLI, an index, and an MCP server in one binary

The repository is a TypeScript project built with tsup. package.json defines three bin entries, docsagent, dag and da, all pointing at the same dist/cli.mjs, which is why the CLI reference table lists aliases next to each command. The runtime dependencies are narrow: the official @modelcontextprotocol/sdk, zod for schema validation, plus tsup and typescript themselves. There is a postinstall hook, node scripts/install.mjs, and a top-level scripts directory, which is consistent with the README's claim that the core is a native C++ engine fetched or placed at install time rather than compiled from the published JavaScript. The README describes the data flow in one direction: docsagent add walks directories and files into an index, the engine keeps vector storage on local disk, and docsagent server exposes that index over MCP as two tools, search and add_docs. The README lists list_documents, remove_document and status as future tools, so today the agent surface is deliberately small. Whether the index survives a reboot, where it lives on disk, and what format it uses are not documented in the README; docsagent status is the only documented way to ask the engine about its own state.

Installing DocsAgent and indexing a first folder

The README gives a single global install step. The package is published as @docsagent/docsagent, and because there is a postinstall script, expect the install to do more than unpack JavaScript.

npm install -g @docsagent/docsagent

After that, the CLI is available under three names. The README's own example adds two directories at once, which is the quickest way to see whether parsing works on your file types:

docsagent add ~/Documents/Legal_Archive ~/Documents/Research

A semantic search from the terminal is the first real use, and it is also the fastest way to sanity-check that the index actually contains what you think it does:

docsagent search "What are the key terms in the Barclays contract?"

If you want the agent to see the same index, start the MCP server. The README shows this as a bare command with no flags:

docsagent server

For Claude Code specifically, the README gives a one-line registration instead of hand-editing a config file:

claude code mcp add docsagent -- docsagent server

Cursor and Windsurf are configured through the UI: Settings, then Features, then MCP Servers, then Add New MCP Server, with type command and command docsagent server. OpenClaw uses a YAML block:

mcpServers:
  docsagent:
    command: "docsagent"
    args: ["server"]

Once connected, the agent gains the search and add_docs tools, so it can index a new folder mid-conversation rather than making you drop back to the terminal.

What the privacy claim does and does not cover

The README's central promise is that parsing, indexing and vector storage all happen on your own hardware. Read literally, that is a statement about the engine, and the architecture supports it: the MCP server runs as a local process launched by the agent, and the tools it exposes are search and add_docs over a local index. The gap is the install step. A postinstall script that fetches a native binary is a network operation, and the README does not document what it downloads, from where, or how it is verified. That is not a contradiction of the privacy claim, but it is the one moment in the lifecycle where the claim is not self-evident, and it is worth inspecting scripts/install.mjs before running the global install on a machine that matters. The same caution applies to the two add-on packages, papersgpt-for-zotero and docsagent-for-obsidian, which the README configures through npx -y, meaning the package is fetched and executed without a confirmation prompt at each launch.

The CLI surface is smaller than the README's tone suggests

The CLI reference table lists five commands: server, add, search, status and stop. That is a complete lifecycle for a background engine, and stop in particular implies the engine runs as a service rather than only in the foreground, though the README does not describe how it is supervised or what happens if it dies. The MCP tool list is where the gap is widest. Only search and add_docs exist today; list_documents, remove_document and status are marked as coming soon. The practical consequence is that there is no documented way to remove a single document from the index once it has been added. For a tool whose selling point is control over private data, the absence of a documented removal path is a real limitation, not a cosmetic one. A user who indexes a folder by mistake has no documented command to undo it. The README also does not document rollback, index migration between versions, or what happens to the index when the underlying files change.

Format support: strong on office documents, silent on scans

The support matrix claims full support for PDF, Word .docx and PPTX. For PDF the README says deep layout analysis and high-speed parsing; for .docx it says table extraction and heading hierarchy are preserved; for PPTX it says slides, shapes and speaker notes are extracted. Those are the right things to preserve if an agent is going to quote from a document, and heading hierarchy in particular matters for retrieval quality on long reports. The omission is OCR. Nothing in the README mentions scanned PDFs or image-only documents, so a library of scanned contracts is likely to produce an index with little usable text. Plain text, Markdown and HTML are also absent from the matrix. If your corpus is mostly note files rather than office documents, the format list is a reason to look at a general-purpose indexer instead. The README also gives no guidance on index size relative to corpus size, which is the number most people want before pointing it at a large archive.

How this differs from a general-purpose local RAG stack

The obvious comparison is a self-hosted retrieval stack built from a vector database plus a parsing library plus a small API, the kind of thing assembled around Chroma, LanceDB or a similar store. The difference in approach is packaging and protocol. A hand-built stack gives you control over chunking, embedding model choice and the schema, and it will index any format you write a parser for. DocsAgent instead fixes those decisions behind a CLI and exposes the result over MCP, which means an agent can use it without a custom integration per tool. The trade-off is that you cannot see or change the chunking strategy, the embedding model is not named in the README, and the only removal mechanism is on the roadmap. For someone who wants an agent to read a folder of PDFs today, the packaged route is less work. For someone who needs to tune retrieval on a specialised corpus, the packaged route is a ceiling.

Maintenance, licensing and what to check before depending on it

The last push to the repository was on 2026-05-19, which is four months before today. The repository is not archived, but there are no retrieved releases, and the version in package.json is 1.1.0. Treat it as a project that has shipped a working core and is still filling in the edges: the README itself lists three MCP tools as coming soon, which is a fair signal about where the surface is. On licensing, the README and package.json both state Apache-2.0, and the README carries an Apache-2.0 badge. Apache-2.0 is permissive and includes a patent grant, but the README does not state the licence of the bundled native engine, which is a separate artifact fetched by the postinstall script. That is the first thing to confirm if you are deploying this inside an organisation, because a permissive licence on the wrapper says nothing about the binary underneath. Upgrading means re-running the global npm install and, presumably, re-indexing, since the README documents no migration step between versions.

Editorial conclusion

Adopt DocsAgent if you already run an MCP-capable agent and want it to read a folder of PDFs, DOCX and PPTX files without uploading them anywhere; the npm package and the CLI are small enough to evaluate in an afternoon. Do not adopt it if your library is mostly scanned images, if you need OCR, or if you need a documented removal path before you hand it a regulated archive, because the README lists no remove command and no OCR support. Before trusting it with anything sensitive, run docsagent add on a throwaway folder, check docsagent status, and inspect what the postinstall script in scripts/install.mjs actually downloads.

Frequently asked questions

Official sources

1. docsagent/docsagent on GitHub
2. Issues
3. README