Skip to main content
Glama

Contributors Forks Stargazers Issues Apache-2.0 License

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.md and an audit log

  • Checkable trust: notes whose status or verified changed outside the plugin are reported as not attested

  • Safe 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

  • okf CLI: lint any OKF bundle in CI

Built With

  • TypeScript

  • Obsidian

  • MCP

  • Zod

  • esbuild

  • Vitest

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 fs module 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-wiki in 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

  1. In Obsidian, open Settings → Community plugins, search for OKF Wiki, install and enable it.

  2. To install by hand instead, download main.js, manifest.json and styles.css from 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.

  1. 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.

  2. Serve it. Open Settings → OKF Wiki. Under Bundles, type the folder path in Add a folder and press Add.

  3. 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.

  4. 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.

  5. 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.json snippet. Copy the one you need before you close it; if you lose it, revoke the token and create another. The status bar now shows OKF MCP :27150 · 1 bundle.

  6. 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.

  7. 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.

  8. 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

  1. In the plugin settings under Bundles, add a folder to serve. Any folder works; it becomes an OKF bundle (an index.md, a log.md and optionally a .okf.yaml policy). Folders that already look like OKF bundles are offered for you to enable.

  2. 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.

  3. Copy a command shown for Claude Code (or the .mcp.json snippet 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 user instead.

  4. 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 concepts and decisions). 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 shows OKF review: N while 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.md and log.md up 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 status or verified outside 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, sources and 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.yaml policy, 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/ and decisions/, with originals in references/raw/. A note has one folder but many tags, and okf_search filters 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

okf_version

string

"0.2"

OKF version of the bundle

content_language

string

en

Language curated notes are written in (BCP 47)

raw_dirs

list

[references/raw]

Folders whose notes are raw sources in any language

non_english_threshold

number

0.05

Largest share of non-Latin letters in a curated note before it counts as non-English

auto_index

boolean

true

Keep index.md files up to date on every write; false means you maintain them by hand

auto_log

boolean

true

Add an entry to log.md on every write

agent_initial_status

draft or stable

draft

Status of notes an agent creates

Roadmap

  • Read-only MCP server with OKF lint and the okf CLI

  • Agent 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 them

Extension 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) and read(args) take the same arguments as the okf_bundles, okf_search and okf_read tools and return copies.

  • onCommit is 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 api object 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:

  1. Fork the Project

  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)

  3. Run npm run typecheck, npm run lint and npm test

  4. Commit your Changes (git commit -m 'Add some AmazingFeature')

  5. Push to the Branch (git push origin feature/AmazingFeature)

  6. 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 bundles

Top 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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables MCP-compatible AI hosts to read, search, link, and write notes in a local Obsidian vault with sandboxed file access.
      1
      1
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Serves 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.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Serves 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.
      12
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Self-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.
      75
      AGPL 3.0