OKF Wiki
Serves Obsidian vault folders as Open Knowledge Format bundles over MCP, enabling AI agents to browse, search, read, graph, history, lint, and write drafts to Obsidian notes with review, provenance, and trust controls.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Everything from About The Project to Support is for people who use the plugin in Obsidian and
needs no programming. Building, testing, the okf CLI and the API for other plugins are in
Building and Extending.
About The Project
OKF Wiki serves folders of your vault to AI agents over MCP as Open Knowledge Format (OKF) v0.2 bundles: plain Markdown with YAML frontmatter that records where knowledge came from, who checked it and when it goes stale. Agents read, search and write through OKF-aware tools; you stay in charge of what counts as reviewed.
Here's why:
Agents that remember things in your notes should say where each fact came from
You should decide which knowledge counts as reviewed, not the agent
Your notes stay plain Markdown that you can read and edit without the plugin
Desktop only. Status: 0.8.0, early.
Features
MCP tools for OKF: browse, search, read, graph, history and lint, plus writes for agents you allow
Drafts first: everything an agent writes starts as a draft that you approve or reject in Obsidian
Provenance: who wrote each note and why, kept in
log.mdand an audit logCheckable trust: notes whose
statusorverifiedchanged outside the plugin are reported as not attestedSafe writes: rate limits, no writes while you type in a note, snapshots and one-click revert
Language policy: curated notes in English, original sources kept as raw files in any language
Extension API: other plugins can read the wiki and follow every change
okfCLI: lint any OKF bundle in CI
Built With
Network use and data
The plugin runs a local MCP server on
127.0.0.1(port 27150 by default, changeable in the settings). It listens on the loopback interface only, so other machines cannot reach it. It starts only once you create an access token.Every request needs a token you create in the settings. Tokens are stored as SHA-256 hashes, are shown once, and can be limited to scopes, bundles and folders.
The plugin contacts no remote service and has no telemetry. Whatever an agent reads goes to the agent you connected, which may send it to its own model provider; that is between you and that agent.
It reads and writes only inside your vault: the bundle folders you enable, and its own state (snapshots, audit log, trust snapshot) in its plugin folder. Files reached through symlinks that lead outside the vault are not served.
It imports Node's
fsmodule to resolve a file's real path (realpath), so that a symlink inside a bundle cannot expose files outside the vault or in its configuration folder, and to keep the hand-over files with the background server in its state folder. It reads and writes notes only through Obsidian's vault API.Background server (optional, Windows, off until you install it). When you press Install in Settings → Background server, and only then, the plugin writes
okf.cjs(the same server, built into the plugin) to.okf-wikiin your user folder and runs it with your installed Node.js to add a Task Scheduler task that starts it at logon. That server then answers agents while Obsidian is closed, on the same port with the same tokens. Start, Stop and Uninstall run the same program; Uninstall removes the task. The plugin starts no other processes.
Related MCP server: vault-mcp
Getting Started
Prerequisites
Obsidian desktop 1.13.1 or later (the plugin does not run on mobile)
An MCP client that speaks streamable HTTP, such as Claude Code
Installation
In Obsidian, open Settings → Community plugins, search for OKF Wiki, install and enable it.
To install by hand instead, download
main.js,manifest.jsonandstyles.cssfrom the latest release into<vault>/.obsidian/plugins/okf-wiki/, then enable the plugin.
To build the plugin from source instead, see Build from source.
First-time setup
From a fresh install to your first approved note. The steps use Claude Code;
other MCP clients work the same way with the .mcp.json snippet.
Choose a folder. Pick a folder in your vault for the knowledge agents may use, or create an empty one, for example
Knowledge. Notes outside it stay private.Serve it. Open Settings → OKF Wiki. Under Bundles, type the folder path in Add a folder and press Add.
Set your ID. Under Agent writes, fill in Your ID, for example your name. You need it to approve notes, and it records your own edits.
Create a token. Under Access tokens, select Create token… and enter a name such as
claude-code. Turn on Scope: Write if the agent may write drafts; leave it off for read only. Press Create token.Copy a command. A dialog shows the token once, with two Claude Code commands (one for this project folder, one for all your projects) and a
.mcp.jsonsnippet. Copy the one you need before you close it; if you lose it, revoke the token and create another. The status bar now showsOKF MCP :27150 · 1 bundle.Connect Claude Code. Paste the command in a terminal, then start
claude:This project folder (
--scope local) adds the server only for the folder you run it in, so run it in the folder where you start Claude Code.All your projects (
--scope user) adds it for every folder.
Avoid
--scope project: it writes the token into the project's.mcp.json, which is often committed to git.Try it. Ask, for example, "Which OKF bundles can you use, and what is in them?" With Write, ask it to write a short note on a topic you know, citing its sources.
Review the draft. Run the command Open review queue and read the new note. Press Approve next to it, or Reject with a reason the agent can read.
Next, read Organizing bundles before your bundle grows, and Access tokens and scopes before you give tokens to more agents.
Usage
See the user manual for step-by-step guides, examples and the full reference.
Connect an agent
In the plugin settings under Bundles, add a folder to serve. Any folder works; it becomes an OKF bundle (an
index.md, alog.mdand optionally a.okf.yamlpolicy). Folders that already look like OKF bundles are offered for you to enable.Under Access tokens, select Create token… to create a token (see Access tokens and scopes). New tokens can read; turn on Scope: Write to let agents write drafts.
Copy a command shown for Claude Code (or the
.mcp.jsonsnippet for other clients). For this project folder only, run it in that folder:claude mcp add --transport http --scope local okf-wiki http://127.0.0.1:27150/mcp/ --header "Authorization: Bearer okf_…"For all your projects, the command uses
--scope userinstead.Ask your agent something about the notes in the bundle.
The agent gets these tools. Reading: okf_bundles, okf_browse, okf_read, okf_read_file
(non-markdown text such as attester code), okf_search, okf_graph, okf_history, okf_lint.
Writing (Write scope): okf_create, okf_update, okf_move, okf_deprecate,
okf_describe_directory, okf_ingest_raw, okf_request_review. Publishing (Publish scope):
okf_publish. Prompts: okf_author_concept and okf_distill_raw.
Access tokens and scopes
Give each agent its own token, created with Create token… under Access tokens in the settings:
Name identifies the agent in logs, for example
claude-code.Limit to bundles and Limit to paths restrict the token to some bundle folders, or to some folders inside them (such as
conceptsanddecisions). Empty means everything.Every token can read. Extra scopes:
Write: create, update, move and deprecate notes and ingest raw sources. New notes are drafts.
Publish, Replace raw sources and Edit computations are for trusted automation only. Publish makes drafts stable without a person's review.
Automated process stamps the token's writes as
process:<name>instead of the agent's name and version.
The token is shown once, together with the Claude Code commands and the .mcp.json snippet. Only a
hash is kept, so if you lose a token, revoke it under Access tokens and create another.
Reviewing what agents write
Agents write drafts. Everything an agent creates starts as
draft. Only you, in Obsidian, can approve a note (Approve this note, or the Review queue); no token can mark knowledge as reviewed by a person. Approving needs Your ID (under Agent writes).The review queue lists drafts and other notes that need you, such as stale notes or notes an agent asked you to review. Open it with the command Open review queue or the ribbon icon (a checklist,
list-checks). The status bar showsOKF review: Nwhile notes wait for you (click it to open the queue). You can tick several notes, or Select all without errors, and Approve selected in one go.Auto approve (optional, off by default). Under Auto approve, list the tokens (and optionally bundles) you trust. A note such a token writes that cites its sources in footnotes and has no lint warnings or review request is approved at once as
process:auto-approve: it becomes stable and machine-confirmed, not reviewed by a person. Notes you approved yourself always come back to you after an agent edits them.Reject. Reject in the review queue, or Reject the agent's latest change to this note…, undoes the agent's latest change to that note (a new draft goes to the trash) and writes your reason to
log.md, where agents read it.
Trust and provenance
Provenance is recorded for you. The server stamps who wrote each note, keeps
index.mdandlog.mdup to date, and, once you set Your ID, records your own edits when you leave a note (turn this off with Record your edits).Trust you can check. If someone edits
statusorverifiedoutside the plugin (another device, a script), the note is reported as not attested instead of trusted.Original sources stay original. Curated notes are English. Material in other languages is stored as a write-once raw source under
references/raw/and cited with footnotes.
Staying in control
Pause or resume agent writes stops every agent write at once.
Revert an agent change… undoes any recent agent write from its snapshot.
Writes are rate limited per token (settings under Agent writes), refused while you are typing in that note, and checked so they cannot drop sources, citations or large parts of a note by accident.
Other commands: Open review queue, Accept edits to this raw source, Convert links in this bundle to OKF form, Reload OKF bundles, Copy MCP endpoint URL, Restart MCP server.
Organizing bundles
One bundle per body of knowledge whose notes link to each other. Links,
sourcesand footnote citations cannot point outside their bundle, and the graph and backlinks stop at its edge, so splitting related notes across bundles breaks them apart.Add another bundle only for a real boundary: a different set of agents that may read or write it (tokens can be limited to bundles), a different auto approve choice, a different
.okf.yamlpolicy, or a folder you share or sync on its own. Bundles cannot be nested.Inside a bundle, use folders for the kind of note and tags for the topic, for example
concepts/,playbooks/anddecisions/, with originals inreferences/raw/. A note has one folder but many tags, andokf_searchfilters by both. Keep folders shallow.Notes outside every bundle are not served, so personal notes and drafts can stay in the same vault.
Configuration
Most settings live under Settings → OKF Wiki (see Usage). Rules for one bundle live
in a .okf.yaml file at the bundle's root, so okf lint in CI and every device apply the same
rules. Agents cannot change it: MCP tools write only .md files. A missing file or key uses the
default.
Option | Type | Default | Description |
| string |
| OKF version of the bundle |
| string |
| Language curated notes are written in (BCP 47) |
| list |
| Folders whose notes are raw sources in any language |
| number |
| Largest share of non-Latin letters in a curated note before it counts as non-English |
| boolean |
| Keep |
| boolean |
| Add an entry to |
|
|
| Status of notes an agent creates |
Roadmap
Read-only MCP server with OKF lint and the
okfCLIAgent writes with drafts, snapshots, revert and rate limits
Review queue, batch approve, auto approve and reject
Extension API for other plugins
See the open issues for a full list of proposed features (and known issues).
Support
Like this project? A coffee keeps it going — every cup funds issues, fixes, and new features.
Building and Extending
This part is for people who build the plugin, check bundles in CI, write plugins on top of OKF Wiki, or contribute. You do not need any of it to use the plugin.
Build from source
Needs Node.js 22 or later:
git clone https://github.com/ysasiwat/obsidian-okf-wiki.git
cd obsidian-okf-wiki
npm ci
npm run build
node scripts/install-plugin.mjs <path-to-vault>The okf CLI
Checks any OKF bundle directory, in or out of Obsidian, for example in CI:
npm install
npm run build:cli
node dist/okf.cjs lint path/to/bundle # conformance and policy; exit 1 on errors
node dist/okf.cjs lint path/to/bundle --strict # also fail on warnings
node dist/okf.cjs index path/to/bundle # exit 1 if index.md files are out of date
node dist/okf.cjs index path/to/bundle --write # regenerate themExtension API for other plugins
Other plugins can read the wiki and follow its changes, but not write to it:
const api = (this.app as any).plugins.plugins["okf-wiki"]?.api;
if (api?.apiVersion === 1) {
const off = api.onCommit((e) => {
// e: { commitId, at, bundle, actor, tool, conceptId, reason?, reverts?,
// changes: [{ path, change: "created" | "modified" | "deleted" }] }
});
this.register(off);
const hits = api.search({ bundle: "Knowledge", query: "remote sensing" }).hits;
const note = api.read({ bundle: "Knowledge", concept_id: hits[0].concept_id });
}bundles(),search(args)andread(args)take the same arguments as theokf_bundles,okf_searchandokf_readtools and return copies.onCommitis called after every commit is on disk: agent writes, your own approvals and edits, and reverts (a revert lists the files it restored). Listeners run after the write and cannot slow or break it.When OKF Wiki is disabled or reloaded, listeners are dropped and the old
apiobject throws; get it again once OKF Wiki is enabled. The types are in src/api.ts.
Contributing
Contributions are welcome. Read CONTRIBUTING.md for the project's rules, then:
Fork the Project
Create your Feature Branch (
git checkout -b feature/AmazingFeature)Run
npm run typecheck,npm run lintandnpm testCommit your Changes (
git commit -m 'Add some AmazingFeature')Push to the Branch (
git push origin feature/AmazingFeature)Open a Pull Request
Development commands:
npm test # vitest
npm run typecheck
npm run lint # eslint-plugin-obsidianmd
npm run build # main.js
npm run bench # UI-thread cost on large synthetic bundlesTop contributors:
License
Distributed under the Apache-2.0 License. See LICENSE for more information. Includes material from Open Knowledge Format (Apache-2.0); the design of the server follows obsidian-local-rest-api (MIT) without using its code. See NOTICE.
Acknowledgments
Open Knowledge Format for the bundle format and sample bundles
obsidian-local-rest-api for the design of a local server inside Obsidian
Model Context Protocol and its TypeScript SDK
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables MCP-compatible AI hosts to read, search, link, and write notes in a local Obsidian vault with sandboxed file access.11MIT
- FlicenseNot gradedqualityBmaintenanceServes as a unified MCP gateway to an Obsidian vault, enabling AI agents to perform hybrid lexical/vectorial semantic search, explore note graphs, and write through consent-based intent batches with conflict detection.-
- AlicenseAqualityCmaintenanceServes a local Obsidian markdown vault over MCP, enabling agents to search, read, build context, verify, and safely propose or apply guarded changes to the knowledge base.12MIT
- AlicenseNot gradedqualityAmaintenanceSelf-hosted server for your Obsidian vaults: a web UI for you, MCP for your AI agents, no Obsidian or plugins required. Agents search notes by keyword or meaning, then read, edit, move and link them across several vaults, and a write is refused if the note changed since the agent read it.75AGPL 3.0