Lexomni MCP
Lexomni MCP is a local knowledge-management server that indexes Markdown and PDF documents into a SQLite FTS5 index so an agent can search, read and note-take inside a _lexomni workspace.
Discover documents —
lexomni_listSourceslists all MDs (user/,agent/) and PDFs (books/) in the workspace, reporting the resolved workspace path, a count, and a warning when it is empty or the index is missing/out of date.Build or refresh the index —
lexomni_buildIndexis the only tool that indexes; it is incremental (skips unchanged files by size + mtime, drops deleted docs), and accepts optionalsources(user/agent/books) andforceto reindex everything.Keyword search —
lexomni_searchDocsperforms literal FTS5 searches over indexed chunks (query ≥ 2 chars, optionalsourcesfilter,limit1–50, default 10) and returns snippets,docId,chunkIndex, source and relative path; it never indexes, so new or changed files require a rebuild.Read document content —
lexomni_readDocreturns a chunk of an indexed document bydocId(≥ 3 chars), with optionalchunkIndex(defaults to 0) andmaxChars(200–20000) to cap response size.Write agent notes —
lexomni_writeNotecreates or updates Markdown files in_lexomni/agent/withfilename,content, and optionalmode(overwritedefault, orappend), limited to 1 MiB per note.Work safely in a configurable workspace — resolution follows
LEXOMNI_WORKSPACE, then the project root (CLAUDE_PROJECT_DIRor the client's first root), then an upward search for_lexomnistopping at the repo root; reads never create folders.Rely on enforced security limits — path traversal, absolute paths, null bytes and symlinks are blocked or ignored, writes are confined to
_lexomni/agent/(verified on real disk path), and PDFs are parsed in sandboxed, read-only Node processes with resource limits.Support multilingual workflows indirectly — the server never translates; the agent expands queries (e.g. "arquitetura em camadas" → "layered architecture") and keeps a living glossary at
_lexomni/agent/glossary.md.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Lexomni MCP search my documents for 'clean architecture'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Lexomni MCP
MCP (Model Context Protocol) server for local knowledge management with Markdown and PDF indexing using SQLite FTS5.
Author: PagansDev (Paulo Gabriel Neves Santos) | Repository: github.com/PagansDev/lexomni-mcp
English
Usage
Requires Node.js 20.16 or newer.
As a local MCP server
Configure your MCP client (e.g.,
.mcp.jsonfor Claude Code,.cursor/mcp.jsonfor Cursor). Pin an exact version:
"lexomni": {
"command": "npx",
"args": ["-y", "lexomni-mcp@0.2.0"],
"env": { "LEXOMNI_WORKSPACE": "_lexomni" }
}A relative LEXOMNI_WORKSPACE keeps a versioned config file portable across machines. Projects set up with @satlab/protocol get this entry from satlab-protocol init, and satlab-protocol update keeps it current.
Add your documents:
_lexomni/user/- User markdown (guidelines, architecture, etc.)_lexomni/agent/- Agent notes (written bylexomni_writeNote)_lexomni/books/- PDFs (books, documentation, etc.)
Ask the agent to run
lexomni_buildIndex. Searches only return what has been indexed.
How the workspace is resolved
LEXOMNI_WORKSPACE, when set. An absolute path is used as is; a relative one is resolved against the project root.The project root is
CLAUDE_PROJECT_DIR(set by Claude Code), otherwise the first root reported by the MCP client, otherwise the current directory.Without
LEXOMNI_WORKSPACE, the server looks for a_lexomnifolder from the project root upwards and stops at the repository root (the first folder containing.git). If none is found, the workspace is<project root>/_lexomni.
Reading never creates folders: user/, agent/, books/ and index/ are created only when lexomni_writeNote or lexomni_buildIndex writes. lexomni_listSources and lexomni_searchDocs always report the workspace they used and return a warning when it is empty, when the index does not exist, or when it is out of date.
Available Tools
Agent handles parameters on its own
lexomni_listSources
Lists all documents (MD and PDF) in the workspace.
Parameters: none
Example:
{
"workspace": "/path/to/project/_lexomni",
"count": 5,
"docs": [...]
}lexomni_buildIndex
Indexes documents into SQLite FTS5 for fast search. This is the only tool that indexes, and it is incremental: documents whose size and modification time did not change are skipped, and documents removed from the workspace are dropped from the index.
Parameters:
sources(optional): array of["user", "agent", "books"]. Limits what is indexed and what can be removed.force(optional): reindex everything, changed or not.
Example:
{ "ok": true, "docsIndexed": 1, "indexed": 1, "skipped": 11, "removed": 0 }lexomni_searchDocs
Keyword search across indexed documents. It never indexes: new or changed files appear only after the next lexomni_buildIndex, and the response carries a warning until then.
The query is literal text. Each word is matched as typed, so hyphens, quotes and colons are safe (third-party, CVE-2024-4367); FTS5 operators such as OR, NEAR or * are not interpreted.
Parameters:
query(required): string, min 2 characterssources(optional): filter by sourcelimit(optional): max results (1-50, default 10)
Example:
{
"query": "clean architecture",
"workspace": "/path/to/project/_lexomni",
"hits": [
{
"docId": "user:user/guidelines.md",
"chunkIndex": 0,
"snippet": "...about [clean] [architecture]...",
"source": "user",
"relPath": "user/guidelines.md"
}
]
}lexomni_readDoc
docId (required)
Type: string Purpose: unique identifier of the document in the index.
Constraint: at least 3 characters. Typical source: taken from a hit returned by lexomni_searchDocs.
chunkIndex (optional) Type: integer Minimum: 0 Purpose: which chunk (piece) of the document to read. If omitted: usually defaults to the first chunk (0), depending on implementation.
maxChars (optional) Type: integer Range: 200–20000 Purpose: maximum number of characters of text to return for that chunk, useful to limit response size.
lexomni_writeNote
filename (required) Type: string Purpose: name of the markdown file to create or update in the agent’s notes area.
Constraint: at least 1 character.
content (required) Type: string Purpose: markdown content to write into the file.
Constraint: at least 1 character.
mode (optional) Type: string Allowed values: "overwrite" – replaces the existing file content entirely. "append" – appends content to the end of the existing file. Default: "overwrite" if not specified.
Security
Path traversal blocked (no
../, absolute paths or null bytes in note names)Write access limited to
_lexomni/agent/, checked against the real path on diskSymbolic links are ignored when indexing and refused when writing notes, so a symlink inside the workspace cannot expose or overwrite files outside it
PDFs are parsed only by
lexomni_buildIndex, each one in a separate, sandboxed Node process (read-only access to the package and that PDF, no writes, no child processes, 100 MB / 512 MB / 60 s limits), with pdf.js string evaluation disabledNotes are limited to 1 MiB
Runtime dependencies are bundled and releases are published from CI with provenance
See SECURITY.md for the supply chain policy, risky components and how to report a vulnerability.
Architecture
_lexomni/ # In user's project
user/ # Guidelines, architecture (read-only)
agent/ # Agent notes (writable)
books/ # PDFs (read-only)
index/ # SQLite FTS5 (generated)
lexomni.sqliteMultilingual Strategy
Lexomni does not translate text internally. To find docs in PT and EN for e.g. :
Agent expands queries before searching:
"arquitetura em camadas" → also searches "layered architecture"
"fila" → also searches "message queue", "job queue"
Living glossary at
_lexomni/agent/glossary.md:Agent learns new terms via web search
Improves search quality over time
Development
npm run build # Bundle into dist/ (index.js, pdf.worker.mjs, sql-wasm.wasm)
npm run dev # Watch mode
npm start # Run built server
npm test # Tests
npm run lint # Lint
npm run typecheck # TypecheckTo run a local build from a clone, point the MCP client to it:
"lexomni-local": {
"command": "node",
"args": ["/path/to/lexomni-mcp/dist/index.js"],
"env": { "LEXOMNI_WORKSPACE": "_lexomni" }
}Related MCP server: Hoard
License
Available Tools
5 toolslexomni_buildIndexB
Generates/updates the SQLite FTS5 index from MDs and PDFs in _lexomni.
Inputs: sources.
lexomni_listSourcesA
Lists available MDs (user/agent) and PDFs (books) in the _lexomni workspace.
Inputs: no named parameters.
lexomni_readDocB
Reads a chunk of an indexed document (by chunkIndex).
Inputs: docId (required), maxChars, chunkIndex.
lexomni_searchDocsB
Searches indexed documents by keyword (FTS).
Inputs: query (required), limit, sources.
lexomni_writeNoteB
Creates/updates a markdown file in _lexomni/agent (agent memory).
Inputs: content (required), filename (required), mode.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct function: listing sources, building the index, searching, reading a chunk, and writing a note. There is no overlap or confusion between tool purposes.
All tools follow a consistent lexomni_verbNoun pattern (listSources, buildIndex, searchDocs, readDoc, writeNote). The naming is uniform and predictable.
Five tools is well-scoped for a document indexing and retrieval server. Each tool earns its place, covering the essential operations without unnecessary bloat.
Core workflows are covered: list sources, build index, search, read chunks, and write agent notes. A minor gap is the lack of a way to enumerate chunks or retrieve document structure, but this is workable for the intended use case.
Maintenance
Related MCP Connectors
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
KnowMan MCP server: search, ask, save and read your Knowledge Base from any MCP client.
MCP server for querying Forkast documentation
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP Server for local knowledge management. Semantic + keywords + tags853 PyPI24MIT
- AlicenseNot gradedqualityDmaintenanceLocal MCP server for indexing personal knowledge into SQLite with hybrid search, chunk-level citations, memory tools, and agent orchestration.4MIT
- AlicenseAqualityCmaintenanceMCP server that indexes Markdown, Word, HTML, and PDF documents into a SQLite knowledge graph with CJK+Latin full-text search and cross-document reference tracking. Runs drift audits to surface stale policies, conflicting research claims, superseded ADRs, and undocumented code exports.109MIT
- FlicenseNot gradedqualityCmaintenanceMCP server that enables full-text search and link navigation over Markdown files as a knowledge graph.-