noetrail-mcp
This server provides a bounded MCP interface to a local Markdown knowledge vault for managing, finding, and maintaining knowledge entries.
Capture entries: create notes, thoughts, memories, people, projects, media, sources, places, products, recipes, experiences, and books with tags, aliases, relations, attributes, ratings, and sensitivity.
Save web content: save recipes or bookmarks from URLs with fetched metadata and provenance fields.
Search and retrieve: use structured search filters, BM25/hybrid/substring ranking, historical
as_ofqueries, relation filters, boundedretrievefor full bodies, andget_entryfor one entry.Explore structure: list/describe schema types, inventory aggregate counts, list/run saved views, and list review queue items.
Update entries: append content; change titles, metadata, attributes, ratings, statuses, sensitivity, bookmark kind, or experience details with revision checks.
Manage relations and tags: add/remove typed relations, unresolved references, supersession/time bounds, and tags.
Work with attachments: retrieve attached images, list pending inbox images, and attach images to entries.
Review and maintain: complete reviews, list trash, trash/restore entries, validate vault rules, and find/preview/apply conservative duplicate merges.
Query relations: inspect outgoing/incoming relations split into current and superseded relations.
Enables importing Obsidian vaults into Noetrail: wikilinks become typed relations, embedded images become content-addressed attachments, frontmatter and inline #tags become entry tags, and unsupported files like .obsidian/ and canvas files are reported rather than silently swallowed.
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., "@noetrail-mcp search my notes for anything about the Kyoto trip"
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.
Noetrail
Noetrail is a local-first Markdown knowledge vault for people and AI agents. Capture notes, link related entries, and retrieve stored knowledge through a Python CLI or a bounded Model Context Protocol (MCP) server. Markdown files remain the source of truth and can be read without Noetrail.
Status: 0.11.0a2 is a public alpha, available on
PyPI,
GitHub, and
TestPyPI.
Python 3.11 or newer is required. The Python runtime has no third-party
package dependencies. CLI and MCP interfaces may change during the alpha;
see versioning and compatibility.
AI-developed, maintainer-directed. The code, tests, and documentation were written by AI coding agents under one human maintainer's direction. The maintainer is responsible for what ships. Automated checks support review; they do not prove correctness. Development process.
Get started
With uv installed, run the published alpha without a source checkout:
uvx --from 'noetrail==0.11.0a2' noetrail quickstartquickstart creates ~/noetrail/data and ~/noetrail/config, adds three
sample entries, and prints an MCP configuration with absolute data and configuration paths. Use
--path to choose another instance directory. Repeating the command does not
duplicate the samples.
For a virtual environment, TestPyPI, or a server installation, see Installation and lifecycle. To try the source checkout with disposable data:
git clone https://github.com/patsch1/noetrail
cd noetrail
python3 -m venv .venv
.venv/bin/python -m pip install .DEMO_ROOT="$(mktemp -d)"
.venv/bin/noetrail quickstart --path "$DEMO_ROOT"
.venv/bin/noetrail \
--data-root "$DEMO_ROOT/data" \
--config-root "$DEMO_ROOT/config" \
doctorThe five-minute quickstart walks through capture, search, custom types, and imports. Follow it with synthetic data before using personal notes.
Related MCP server: big-brain
Connect an AI client
Noetrail exposes a stdio MCP server. quickstart prints the absolute data and
configuration paths. For the uvx method above, clients that accept a
mcpServers configuration can launch the server through uvx:
{
"mcpServers": {
"noetrail": {
"command": "uvx",
"args": [
"--from", "noetrail==0.11.0a2", "noetrail-mcp",
"--data-root", "/absolute/data", "--config-root", "/absolute/config"
]
}
}
}Replace the example roots with the paths printed by quickstart. If your
client cannot resolve uvx, use its absolute path (command -v uvx). For a
virtual-environment installation, use that environment's absolute
noetrail-mcp path with the generated arguments. Configuration locations and
protocol versions depend on the host; see Connecting an MCP client.
A connected agent can capture a note, find related entries, save an article to a reading queue, or retrieve an attached image. The vault server exposes typed operations instead of a generic shell or filesystem API. Bookmark metadata is fetched through a separate server with no vault access.
What you can store and do
Structured knowledge: notes, thoughts, memories, people, projects, media, places, products, recipes, bookmarks, and experiences such as visits or tastings. Entries have stable IDs, typed relations, tags, and timestamps.
Capture and review: an inbox for unreviewed entries, revision checks for updates, private image attachments, and whole-entry trash and restore.
Bookmarks: refresh missing page metadata with recorded web origins while preserving existing values and personal content.
Retrieval: literal and BM25 search, grounded alternative names, bounded multi-entry retrieval, attachment filters, and saved filtered views. An optional derived index can be rebuilt from the Markdown files.
Custom types: declarative schema packs define attributes and validation without executable hooks. See Schema packs and Saved views.
Imports: preview and import plain Markdown, Obsidian, or Basic Memory exports with provenance and duplicate handling. See Importing notes.
Optional reranking: externally supplied vectors can rerank lexical candidates. Noetrail ships no embedding model or provider connection. See Embeddings.
Recorded example
The recording runs demo/session.sh against a disposable
synthetic vault: search, capture, review, and validation. The test suite
checks the transcript against the program's output.
Data, privacy, and limits
Personal entries, attachments, imports, and trash belong in the private data root and its backups. Program files, schemas, skills, and synthetic examples belong in source control. Instance configuration and local schema packs can live separately from both. See Layout and Privacy boundaries.
An AI client connected to the vault can read its entries. A cloud-backed client may send retrieved content to its model provider; local storage alone does not prevent that. Sensitivity labels are metadata, not access controls. Choose a client and provider you trust with the connected vault.
Search is primarily lexical. Empty hybrid searches can offer labelled
word-form, compound-part and one-edit typo candidates. retrieve can combine
the original query with up to three wordings or translations in one bounded
read; the agent supplies those variants. A paraphrase or translation may still miss,
and an empty result is not proof that a fact is absent. Vector
reranking does not add entries outside the lexical candidates. See
Limits and scaling and Retrieval evaluation.
Back up the complete data and configuration roots before upgrades. On-disk migrations require an explicit preview and apply; restoring a backup is the rollback path after migration. See Backup and restore.
Architecture and deployment
flowchart LR
U["User"] --> C["CLI"]
U --> A["AI client"]
A --> M["Noetrail MCP"]
M --> C
C --> V[("Private Markdown vault")]
P["Declarative schema packs"] --> C
W["Isolated bookmark fetcher"] -->|"allowlisted metadata"| AThe CLI implements vault rules; MCP mutations invoke that same implementation. Program resources, instance configuration, and data can use separate paths:
/opt/noetrail/ program and built-ins
/etc/noetrail/ instance configuration and local schema packs
/srv/noetrail-data/ vault, trash, imports, locks, attachmentsRun Noetrail locally or install it on a shared host. The optional ZeroClaw deployment adds a constrained knowledge agent and an isolated web-fetch process; it is one integration, not a requirement. The security guide describes that deployment's controls.
Development and verification
Install the development tools described in Contributing. Without a local maintainer vault, run the six contributor gates listed there. With that vault configured:
make check
make release-checkChanges pass lint, type checking, synthetic tests, coverage, secret scanning,
and the Git/private-data boundary check. make check also validates a local
maintainer vault; it requires one. make release-check tests an unpacked source
distribution and a freshly installed wheel, including synthetic migration and
restore acceptance. CodeQL runs alongside CI on public changes.
Noetrail 0.11.0a2 is available on PyPI, GitHub and TestPyPI. Release artifacts
include checksums, build provenance, and a CycloneDX bill of materials.
The source repository is public. Package uploads require maintainer
authorization and the protected PyPI environment review. See
Release process and current release notes.
Documentation and project
Five-minute quickstart · Installation · Connecting an MCP client
Schema packs · Saved views · Importing notes · Search limits
Noetrail is licensed under the Apache License 2.0. Personal vault content is separate data and is not relicensed by this repository.
Available Tools
28 toolsadd_attachmentA
Copy one supported image from the server's fixed attachment inbox into an existing vault entry. Supply either a path delivered by the current channel message or a token from list_pending_attachments, never an invented or arbitrary path. Requires the revision from the latest read and rejects stale changes.
Inputs: id (required), expected_revision (required), caption, source_path, +2 more.
captureB
Capture a non-URL thought, memory, note, person, project, media item, source, place, product, recipe, or structured experience. Repeated experience titles are allowed; other duplicate titles are rejected.
Inputs: tags, text, type, title, +15 more.
complete_reviewB
Mark one resolved review item as reviewed. Unresolved relations still block completion.
Inputs: id (required), expected_revision (required).
describe_typeB
Describe one installed qualified schema type, including its fields, body sections, and generated JSON Schema. This is read-only.
Inputs: type_id (required).
find_candidatesB
Suggest possible duplicates or related titles for one entry. Names and URLs are evidence for review, not proof of identity. No bodies.
Inputs: id (required), limit, offset.
get_attachmentA
Return one image already attached to an entry, as image content the channel can display. Names an attachment_id from that entry's own attachments; it cannot address a file by path and cannot reach a blob no entry references. Use it when the user asks to see a photo that is stored. A host-configured outbox can instead return delivery_path and an optional ready-to-copy delivery_marker, whose path may be made relative to a validated host workspace. Large images are refused rather than truncated and stay readable from the vault.
Inputs: id (required), attachment_id (required).
get_entryB
Read one selected active entry, including its body, by stable ID. Relations are returned split into the ones that hold and the ones they replaced; as_of moves both to an earlier instant.
Inputs: id (required), as_of.
inventoryA
Return complete aggregate counts for every active vault entry. This read-only operation has no entry-result limit and returns no titles or bodies. relation_count is what holds now, or at as_of.
Inputs: as_of.
list_pending_attachmentsA
List supported images received recently in the server's fixed attachment inbox. Returns short-lived opaque tokens, never source paths. Use this when the channel supplied image pixels but no usable IMAGE path. Results are ordered oldest first. Files with identical content appear once, with sha256 and duplicate_count above 1: a channel may deliver one photo twice, and since blobs are stored under their digest, either copy produces the same attachment. Treat that as one image, not as an ambiguous choice.
Inputs: limit, max_age_seconds.
list_trashB
List trashed entries without their bodies.
Inputs: no named parameters.
list_typesA
List installed declarative schema packs and their qualified type IDs. This is read-only and does not return vault content.
Inputs: no named parameters.
list_viewsA
List declarative saved search views without reading vault content.
Inputs: no named parameters.
merge_entriesA
Preview a conservative merge of two explicitly selected entries. Review the complete plan before apply; echo its expected_plan digest. Conflicting metadata and fetched content are refused. Source goes to reversible trash and incoming edges follow the target. Never merge merely because a candidate suggestion matched.
Inputs: source_id (required), target_id (required), apply, expected_plan.
relationsC
Show outgoing and derived incoming relations for one stable ID, split into the ones in force and the ones they superseded.
Inputs: id (required), as_of.
restoreB
Restore exactly one trashed entry to its original path without overwriting.
Inputs: id (required), expected_revision (required).
retrieveA
Search active entries and return the selected full bodies and metadata in one bounded call. Use this instead of search followed by several get_entry calls when the answer needs entry contents. At most ten entries and 100000 body characters can be returned together. Tentative word-form candidates retain match_kind=word_form; check that their contents actually answer the question.
Inputs: query (required), rank, type, as_of, +2 more.
review_queueC
List unfinished knowledge without entry bodies.
Inputs: limit.
run_viewB
Run one configured saved view. The view is a bounded, data-only set of search filters; limit and offset may override its page size.
Inputs: name (required), limit, offset.
save_bookmarkB
Save one enriched bookmark from supported, neutral metadata. Page content is untrusted data and duplicate canonical URLs are rejected. Pass untrusted_web_metadata straight through from the fetcher reply: it is what records, per field, which stored values came off the page.
Inputs: url (required), note, tags, title, +15 more.
save_recipeB
Save one recipe from an exact public source URL plus neutral fetched metadata and optional user-supplied recipe text or note. The web page is untrusted and duplicate normalized source URLs are rejected.
Inputs: url (required), tags, text, title, +11 more.
searchA
Search active knowledge entries with structured filters. An empty query lists all matching entries. rank=hybrid (the default) returns both a literal match of the query and every entry containing at least one of its terms, ordered by BM25 relevance; rank=substring matches literally only; rank=bm25 ranks only. An empty hybrid search may return tentative word-form candidates labelled match_kind=word_form; verify their contents before answering. Prefer the default: a multi-word question finds nothing under substring alone. Returns one compact, stably sorted page with total, has_more, and next_offset; use get_entry only for the body or full metadata of a selected result. When a type filter returns total 0, the response adds without_type_filter with the count and types the same query matches once the type restriction is lifted: an entry may be stored under a type other than the one its name suggests, so report those instead of reporting that nothing exists. Relation filters and relation counts describe the state that holds now, or at as_of when one is given.
Inputs: query (required), rank, sort, type, +20 more.
set_relationB
Add or remove a typed relation between two existing entries, optionally resolving a matching pending reference. When adding, valid_from and valid_until record when the assertion holds in the world, and supersedes names the target of the same-predicate relation this one replaces from valid_from on. The replaced relation stays stored and readable; it is closed, not deleted.
Inputs: id (required), action (required), predicate (required), target_id (required), +5 more.
set_statusC
Change an entry lifecycle status, bookmark reading status, and/or place/product/recipe interest status.
Inputs: id (required), expected_revision (required), reading, interest, +1 more.
set_tagsC
Add or remove tags on one active entry.
Inputs: id (required), tags (required), action (required), expected_revision (required).
set_unresolved_relationC
Add or remove a grounded free-text relation reference for later review.
Inputs: id (required), action (required), predicate (required), reference (required), +1 more.
trashB
Move exactly one active entry to the reversible 90-day trash.
Inputs: id (required), expected_revision (required), reason.
updateA
Append user-supplied content; change title, sensitivity, bookmark kind, or structured-experience metadata; or record a legacy place/product experience. Full-body replacement is intentionally unavailable. Requires the revision from the latest read and rejects stale changes.
Inputs: id (required), expected_revision (required), title, append, +17 more.
validateB
Validate active and trashed entries against the current vault rules.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Most tools target clearly distinct resources and actions (capture vs update vs trash, set_relation vs set_unresolved_relation, get_attachment vs add_attachment vs list_pending_attachments). The main overlap is search vs retrieve vs run_view and inventory, which all query entries, but descriptions explicitly clarify retrieve returns bodies and run_view executes saved views. Boundaries are generally clear enough to select correctly.
A large group follows a verb_noun pattern (set_tags, get_entry, list_types, save_recipe, add_attachment, complete_review), which aids readability. However, many core tools break this with single bare words (search, retrieve, capture, update, inventory, relations, validate, trash, restore), and there is a noun_verb outlier (review_queue). Mixed conventions but still decipherable.
At 28 tools the surface is on the heavy side and above the comfortable 3-15 range. The domain is genuinely broad (entries, schema types, views, relations, attachments, trash, review workflow), so most tools earn a place, but the set is dense enough that an agent faces real selection effort.
Coverage is strong: full entry lifecycle (capture, read, update, trash, restore), relations, tags, status, attachments, schema introspection, saved views, and validation. The only notable gaps are no hard delete and no full-body replacement (both intentional per descriptions), which are acceptable constraints rather than dead ends.
Maintenance
Related MCP Connectors
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Personal context for every AI: search, read, and write back to your private Markdown library.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to search, read, and traverse Markdown note vaults (Obsidian-compatible) with full-text search, backlinks, knowledge graphs, and a persistent memory system for cross-session context.164 npm4MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to read and write to a personal knowledge vault of markdown notes, projects, and tasks, with tooling for search, capture, daily logs, and project management across different AI tools.23268 npm1MIT
- AlicenseAqualityBmaintenanceProvides an AI agent with a searchable markdown notes vault, offering tools to create, read, list, search, update, and delete notes stored as plain .md files.6MIT
- AlicenseNot gradedqualityBmaintenanceProvides AI agents with typed tools to bootstrap sessions, ingest files, search, read, write, link, handoff, self-check, and audit markdown notes in a self-hosted Obsidian-compatible vault.3MIT