Skip to main content
Glama

llm-wiki-kiss

License: AGPL v3 or later Python 3.10+ MCP Tests Made with KISS

A KISS self-hosted wiki for AI agents — Markdown files on the filesystem, uniform access via MCP (stdio) and an optional REST/HTTPS fallback. Same content, no matter which agent: Claude Code, Open Cloud, Perplexity, Python scripts, browser.


Contents


Related MCP server: kiwiki

TL;DR

Imagine you have a bunch of notes about your work scattered across random chat windows, sticky notes on your desk and half-finished documents on your laptop. Now imagine one of those smart AI assistants (the "LLM" thing) that everybody keeps talking about) could read all of those notes, learn from them, add new ones, and never forget anything you told it. Cool, right?

That's exactly what this project does.

The idea is stupidly simple: take a normal folder full of normal .md files (the same kind of files you already write everywhere), and let any AI assistant read and write them through a standard protocol called Model Context Protocol (MCP). No magic, no database, no complicated setup. Just plain text files that you and the AI can both understand.

Three flavours of access, pick the one you want:

  1. MCP stdio — the AI assistant launches this tiny program on your computer, talks to it through standard input/output (the kind of thing every program already does). No internet needed, super fast, super safe. This is the default and it works offline.

  2. CLI — a normal command-line tool (wiki-kiss) that you can run from your terminal. Great for scripts, cron jobs, and shell power users.

  3. MCP Streamable HTTPS — if you want the AI to connect over the network (maybe from another machine or a cloud service), turn on TLS + Bearer token authentication. Off by default, enabled with one command.

That's it. No database to install, no Docker to learn, no cloud account to create. If you know how to clone a Git repo and run a shell script, you've already understood 90% of the project.

If you want the long, detailed version of how to actually use it, keep reading. The whole README is basically a friendly walkthrough of every command, every setting, and every file, with copy-pasteable examples. Have fun.


Why this exists

Knowledge shared between AI agents today lives scattered across tools, notebooks and conversations that disappear the moment you close the tab. This project provides a persistent, portable, 100% user-controlled knowledge base:

  • šŸ“ .md or .html files readable with any editor

  • 🧠 A standardized MCP server any agent can use

  • 🌐 A minimal REST API as a fallback for clients that do not support MCP

  • 🪶 No database, no CMS, versioned with Git

  • šŸ”Œ Works anywhere: local, private server, container, codespace

  • šŸ”’ One process per wiki, one token per process, file lock between threads and processes

  • 🧰 CLI + REST + stdio MCP + Streamable HTTPS MCP, all in a few hundred lines of Python

  • šŸ§‘ā€šŸ’» A configurable Agent Skill generator so a single LLM client gets a tailored skill per instance

The goal is to be a small, portable, auditable replacement for any closed-source "AI memory" service.


Features

  • Filesystem storage: one folder with Markdown files and relative links. No SQL, no MongoDB, no Redis. tar the folder and you have a full backup.

  • KISS concurrency: reads are lock-free; writes are serialised per root through a thread RLock paired with an OS file lock, so two processes writing the same wiki never corrupt it. Pages and indexes are published atomically with tempfile + fsync + os.replace, so a reader never sees a partial file.

  • MCP stdio server with five tools: list_pages, read_page, search, write_page, append_note. Same JSON schema for all transports.

  • MCP Streamable HTTPS server (MCP 2025-06-18) for remote clients. TLS and Bearer token are mandatory; if the token is not configured the server stays fail-closed and replies 503.

  • FastAPI REST API protected by the same Bearer token, with OpenAPI docs on /docs. REST accepts loopback binding only.

  • Local CLI (wiki-kiss / scripts/wiki.sh) for offline content access. Reads return raw Markdown, mutations return JSON.

  • Per-instance Agent Skills: scripts/onboard-agent.sh generates a tailored SKILL.md plus a protected connection.json and an MCP client config ready for Claude Code, Claude Desktop, Pi or any Agent Skills compatible client.

  • MCP prompts (v0.4.0+): the same skills are also exposed as MCP prompts (server-pushed, no client install) so any compatible agent can load them at runtime via prompts/get.

  • Configuration persistence: root, token, host, port, TLS certificate and key are stored in .wiki-kiss.env with mode 0600. scripts/configure.sh rotates the token, toggles HTTPS, restarts the services and writes the file atomically.

  • Path safety: pages can never escape the wiki root, no .., no NUL bytes, max 2 MiB per page, OS-enforced locking.

  • Privacy by default: public health checks never expose root, paths or content; HTTP responses set Cache-Control: no-store, X-Content-Type: nosniff, Referrer-Policy: no-referrer.

  • Scripted operational tools: setup, configure, onboard, start, stop, status, run-tests, onboard-agent. All shell scripts pass bash -n and live in scripts/.

  • Continuous integration: GitHub Actions matrix on Python 3.10–3.13 with pytest, ruff, Bash validation, MCP stdio and Streamable HTTPS smoke tests, plus Gitleaks and Dependabot.


Quick start (5 minutes)

Requirement: Python 3.10+.

# 1. Clone and configure
git clone https://github.com/hor-net/llm-wiki-kiss.git
cd llm-wiki-kiss

# 2. Install, pick the root, generate the token and leave HTTPS off
scripts/setup.sh --with-dev --root ./wiki --https off

# 3. Read the generated token and start the local REST API
export WIKI_MCP_TOKEN="$(scripts/configure.sh --show-token)"
scripts/start-rest.sh

# 4. Verify (health is public, data is authenticated)
scripts/status.sh
curl http://127.0.0.1:8765/health
curl -H "Authorization: Bearer $WIKI_MCP_TOKEN" http://127.0.0.1:8765/stats

To integrate with Claude Code / Claude Desktop / Open Cloud / Perplexity:

scripts/onboard-agent.sh --name customer-wiki --label "Customer Wiki"

Copy the output into your client configuration file and restart it.


Architecture

llm-wiki-kiss/
ā”œā”€ā”€ wiki/                  # Markdown data (your wiki)
│   ā”œā”€ā”€ index.md
│   ā”œā”€ā”€ projects/  notes/  decisions/  references/  assets/  logs/
ā”œā”€ā”€ wiki_core/             # filesystem logic (WikiStorage, validation, search)
ā”œā”€ā”€ mcp_server/            # MCP stdio + Streamable HTTPS server (5 tools)
ā”œā”€ā”€ rest_api.py            # FastAPI HTTP fallback
ā”œā”€ā”€ scripts/               # setup, configure, CLI, start, stop, status
ā”œā”€ā”€ tests/                 # pytest + MCP smoke tests via stdio and HTTPS
ā”œā”€ā”€ .agents/skills/        # template SKILL.md for AI agents
ā”œā”€ā”€ CONFIGURATION.md       # root, token, TLS and HTTPS toggle
ā”œā”€ā”€ ONBOARDING.md          # per-instance skill generation
ā”œā”€ā”€ SECURITY.md            # threat model and reporting
ā”œā”€ā”€ CONTRIBUTING.md        # contributor guide
ā”œā”€ā”€ CHANGELOG.md           # release history
ā”œā”€ā”€ pyproject.toml, requirements*.txt, .env.example, .gitignore
ā”œā”€ā”€ LICENSE                # GNU AGPL v3 or later
└── README.md

Request flow for the most common case (local agent, stdio):

+-----------------+        stdio JSON-RPC        +-------------------+
|  LLM client     |  <----------------------->  |  mcp_server.py    |
|  (Claude Code,  |                             |  (WikiStorage)    |
|   Pi, …)        |                             +---------+---------+
+-----------------+                                       |
                                                          v
                                              +-----------+-----------+
                                              |  wiki/ Markdown files  |
                                              |  .wiki-kiss.lock (OS)   |
                                              +-----------------------+

Request flow for remote MCP:

+-----------------+        HTTPS + Bearer        +-------------------+
|  Cloud client   |  <----------------------->  |  mcp_server.http   |
|  (Open Cloud)   |                             |  (BearerAuthMW)    |
+-----------------+                             +---------+---------+
                                                          |
                                                          v
                                              +-----------+-----------+
                                              |  WikiStorage + TLS    |
                                              +-----------------------+

Manual installation

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt    # + requirements-dev.txt for development

scripts/setup.sh automates the same flow and can also generate the token and HTTPS configuration in one step.


Configuration

scripts/configure.sh selects the root, generates or rotates the token and actually turns the MCP HTTPS interface on or off. Settings are persisted in .wiki-kiss.env with mode 0600.

scripts/configure.sh                              # interactive mode
scripts/configure.sh --root ~/private-wiki --https off
scripts/configure.sh --show-token
scripts/configure.sh --rotate-token
scripts/configure.sh --https off                  # stops and disables HTTPS
scripts/configure.sh --https on                   # reuses the saved cert and key

HTTPS always requires a PEM certificate and key. The full guide, including a self-signed certificate for local tests, lives in CONFIGURATION.md.

Environment variables

Variable

Default

Purpose

WIKI_ROOT

./wiki

Folder containing the Markdown files

WIKI_MCP_TOKEN

(auto)

Bearer token required for HTTP transports

WIKI_HTTPS_ENABLED

0

Turns MCP HTTPS on/off

WIKI_HTTP_HOST

127.0.0.1

Host for MCP HTTPS

WIKI_HTTP_PORT

8766

Port for MCP HTTPS

WIKI_MCP_URL

(unset)

Public URL https://.../mcp (required with 0.0.0.0)

WIKI_TLS_CERT

(unset)

PEM certificate for HTTPS

WIKI_TLS_KEY

(unset)

PEM private key for HTTPS

WIKI_LOG_LEVEL

INFO

Python log level

DEFAULT_HOST

127.0.0.1

REST host

DEFAULT_PORT

8765

REST port

NO_COLOR

(unset)

Disable colour output


Offline local usage

Neither MCP stdio nor the CLI open ports or require a token. Both access the single WIKI_ROOT directly and reuse WikiStorage for locking, validation and atomic writes.

MCP stdio

The client configuration shown later runs:

.venv/bin/python -m mcp_server --root /path/to/wiki

Communication happens over the local subprocess stdin/stdout: no HTTP, DNS or network connection involved.

CLI

From the checkout use scripts/wiki.sh; after installing the package the wiki-kiss console script is also available.

scripts/wiki.sh list
scripts/wiki.sh read notes/idea.md
scripts/wiki.sh search "text to find" --subdir notes
scripts/wiki.sh write notes/idea.md --content $'# Idea\n\nContent'
printf '# From stdin\n\nText\n' | scripts/wiki.sh write notes/stdin.md
scripts/wiki.sh append logs/manual.md --content "Operation completed"
printf 'Note from a local process\n' | scripts/wiki.sh append
scripts/wiki.sh stats
scripts/wiki.sh rebuild-indexes

The root can be picked with --root /path/wiki or via WIKI_ROOT. read outputs raw Markdown; list, search, write, append and stats emit JSON, so they can be reused by scripts and local agents. Local access follows filesystem permissions: for a private wiki use an unshared root and, on Unix, restrictive permissions such as chmod -R go-rwx /path/wiki.


The 5 MCP tools

Tool

Purpose

list_pages

Lists pages, optional subdir.

read_page

Reads the content of a page by path.

search

Case-insensitive full-text search with snippet and line.

write_page

Creates or overwrites a page; appends .md when missing.

append_note

Appends text. Defaults to the daily log logs/YYYY-MM-DD.md.

All paths are relative to the wiki root and separated by /.

Concurrency

Reads are lock-free. write_page, append_note and index regeneration are serialised per root through .wiki-kiss.lock, valid across threads and processes. Writes use temporary files, fsync and os.replace: a reader never sees a partial file, only the previous or next complete version. Distinct instances or containers remain independent. The MCP handlers run the filesystem operations in the standard thread pool so they never block the event loop.

Coordination only applies to mutations that go through WikiStorage. Scripts and editors that write directly to the root bypass the lock.

Quick examples

// list_pages
{ "subdir": "notes" }

// read_page
{ "path": "notes/example-note.md" }

// search
{ "query": "MCP", "max_results": 20 }

// write_page
{ "path": "notes/idea.md", "content": "# Idea\n\n...", "overwrite": false }

// append_note (path optional: defaults to today's log)
{ "content": "Refactor started.", "heading": "Refactor" }

REST API

Method

Endpoint

Description

GET

/health

Health check

GET

/stats

Wiki statistics

GET

/pages?subdir=...

List pages

GET

/pages/{path:path}

Read a page

PUT

/pages/{path:path}

Write a page

GET

/search?q=...

Full-text search

POST

/notes

Append note (defaults to daily log)

GET

/docs

Interactive OpenAPI (Swagger UI)

All REST endpoints, including /docs and /openapi.json, require Authorization: Bearer <WIKI_MCP_TOKEN>. Only /health is public and it does not expose root, paths or content. HTTP responses set Cache-Control: no-store. Without a token the service stays fail-closed and replies 503 without serving data.


MCP Streamable HTTPS (cloud clients)

The MCP server is also exposed via HTTPS with the Streamable HTTP transport (MCP 2025-06-18), so MCP-aware cloud clients (Open Cloud updated, etc.) can connect without launching a subprocess.

scripts/configure.sh --https on \
  --host 0.0.0.0 \
  --port 8766 \
  --url https://wiki.example.com/mcp \
  --cert /path/to/fullchain.pem \
  --key /path/to/privkey.pem

The client connects to https://HOST:8766/mcp with:

POST /mcp
Authorization: Bearer long-random-secret
Accept: application/json, text/event-stream
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Turn it off at any time with scripts/configure.sh --https off. MCP stdio and the CLI keep working. For a public service use a trusted certificate (for example Let's Encrypt) or terminate TLS in a reverse proxy.

The process serves a single root (WIKI_ROOT) with a single mandatory token (WIKI_MCP_TOKEN). Without a token both HTTP transports stay fail-closed. To serve different customers or wikis, run separate instances or containers with independent filesystems, tokens and ports. Never share volumes or tokens across customers.


MCP client configuration

Example snippet for Claude Code / Claude Desktop / Open Cloud / Perplexity (generated by scripts/onboard-agent.sh):

{
  "mcpServers": {
    "wiki-kiss": {
      "command": "/path/to/project/.venv/bin/python",
      "args": ["-m", "mcp_server", "--root", "/path/to/project/wiki"],
      "cwd": "/path/to/project",
      "env": {
        "WIKI_ROOT": "/path/to/project/wiki",
        "WIKI_LOG_LEVEL": "INFO"
      }
    }
  }
}

Client

Configuration file

Claude Code

.mcp.json in the project root (or global ~/.claude.json)

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

Open Cloud

mcpServers section in the client settings

Perplexity

MCP section of the client settings (when supported)

After saving the configuration restart the client so it reloads the list of MCP servers.


Skills for agents

In .agents/skills/ you find two ready SKILL.md files loadable by TRAE, Claude Code and other compatible agents:

Skill

When the agent uses it

wiki-kiss-bridge

Reading, searching, writing, citing wiki content.

wiki-kiss-operator

Installing, starting, stopping, integrating or troubleshooting.

Copy the folders into ~/.claude/skills/ (or the path expected by your client) to use them locally. Pi automatically discovers project skills under .agents/skills/.

MCP prompts (server-pushed, no client install)

Since v0.4.0 the two skills are also exposed as MCP prompts. The server advertises them via the standard prompts/list method and returns their body via prompts/get, reading the live SKILL.md content on every request. This means:

  • A connecting agent (Claude Code, Pi, Open Cloud, ...) sees the prompts listed in its prompts/list response and can load them with a prompts/get call, without any local file install.

  • The skill content is always fresh: edit the SKILL.md and the next prompt fetch returns the new version to every connected client.

  • No credential is exposed: the SKILL.md body is operator documentation, the per-instance token is still delivered by scripts/onboard-agent.sh as connection.json.

This is the recommended way to deliver skills when several clients connect to the same wiki over MCP HTTP/HTTPS: one place to edit, every client up-to-date automatically.


Custom onboarding

Generate a personalised Agent Skill for the configured instance:

scripts/onboard-agent.sh --name customer-wiki --label "Customer Wiki"

auto mode uses HTTPS when it is enabled and configured, otherwise MCP stdio over the filesystem. The skill contains:

  • a tailored SKILL.md;

  • references/connection.json with root, URL and token;

  • references/mcp-config.json ready to be adapted to the client.

The default destination .agents/skills/generated/ is git-ignored. Files have mode 0600 and contain real credentials: do not share or commit them. After a token rotation regenerate the skill with --force. See ONBOARDING.md for local/remote modes, global install and revocation.


Management scripts

All scripts accept --help. Logs go to var/log/, pids to var/run/.

Script

Purpose

scripts/setup.sh

Creates or updates the venv and installs dependencies.

scripts/setup.sh --with-dev

+ pytest, ruff, httpx.

scripts/setup.sh --recreate

Rebuilds the venv from scratch.

scripts/configure.sh

Configures root, token and MCP HTTPS state.

scripts/onboard-agent.sh

Generates a private skill with URL/path and credentials.

scripts/start-mcp.sh

Starts the MCP stdio server (local, no network).

scripts/wiki.sh

Local CLI to read, search and edit the wiki.

scripts/start-mcp-http.sh

Starts MCP HTTPS only when enabled and configured.

scripts/start-rest.sh

Starts the REST API in background.

scripts/start-rest.sh --foreground

Starts the REST API in foreground.

scripts/start-rest.sh --reload

Development mode with auto-reload.

scripts/stop.sh {mcp|mcp-http|rest|all}

Stops one or more services.

scripts/status.sh

Shows status, pids and logs.

scripts/onboard-agent.sh

Generates a private skill with URL/path and credentials.

scripts/run-tests.sh

Wrapper around pytest (accepts pytest arguments).

Main variables: WIKI_ROOT, WIKI_MCP_TOKEN, WIKI_HTTPS_ENABLED, WIKI_HTTP_HOST, WIKI_HTTP_PORT, WIKI_MCP_URL, WIKI_TLS_CERT, WIKI_TLS_KEY, WIKI_LOG_LEVEL, DEFAULT_HOST, DEFAULT_PORT, NO_COLOR. configure.sh manages .wiki-kiss.env, which takes precedence over any .env.


Tests and quality

scripts/run-tests.sh -q
.venv/bin/python -m pytest -q
.venv/bin/python tests/smoke_mcp.py       # MCP stdio smoke test
.venv/bin/python tests/smoke_mcp_http.py  # MCP Streamable HTTPS smoke test
.venv/bin/ruff check wiki_core mcp_server rest_api.py tests

The GitHub Actions matrix runs pytest on Python 3.10, 3.11, 3.12 and 3.13, plus ruff, Bash validation and the two smoke tests.


Wiki layout

Example organisation of the wiki/ folder:

wiki/
ā”œā”€ā”€ index.md
ā”œā”€ā”€ projects/         # project documentation
ā”œā”€ā”€ notes/            # quick notes, ideas, observations
ā”œā”€ā”€ decisions/        # ADRs (NNNN-title.md)
ā”œā”€ā”€ references/       # external links and sources
ā”œā”€ā”€ assets/           # images, attachments
└── logs/             # append-only logs (YYYY-MM-DD.md)

Conventions:

  • Plain Markdown files, UTF-8.

  • kebab-case filenames.

  • Each page starts with a level-1 title (# Title).

  • Internal links are relative: [another page](../notes/idea.md).

  • No mandatory frontmatter: add it only when real metadata is needed.


Philosophy

KISS first.

  • The wiki holds stable knowledge: decisions, projects, references.

  • Conversational memory is handled elsewhere (e.g. QMD): it covers short-lived, dynamic context, not long-term knowledge.

  • MCP makes that knowledge available to any agent: one contract, infinite integrations.

  • No database: tar czf wiki-$(date +%F).tgz wiki/ is the backup.

  • No lock-in: everything is text, everything is versionable with Git.


Advantages and limits

Advantages: full control, trivial backup, immediate migration, easy debugging, compatibility with multiple AI agents, gradual growth, auditable codebase, no cloud lock-in.

Limits: no automatic backlinks, no native database, no rich UI, no distributed transactions. Quality depends on discipline in writing and naming conventions. The file lock relies on a filesystem that supports operating-system locks correctly. Multi-tenant hosting must be done by running multiple processes or containers, not by adding routing inside the process.


Contributing

Issues and PRs are welcome. Read CONTRIBUTING.md before proposing changes. For vulnerabilities use the private procedure described in SECURITY.md, never a public issue.


License

GNU AGPL v3 or later — Copyright (C) 2026 Hornet SRL.

You can use and sell the service as long as you respect the licence terms. In particular, the AGPLv3 requires you to offer the source of the modified version to the users that run it as a network service. User data and wikis do not become part of the licensed source code.


Credits

Project inspired by the Model Context Protocol paper (https://modelcontextprotocol.io) and the Unix philosophy "do one thing and do it well".

Available Tools

5 tools
append_noteA

Quickly appends a note or log entry. If 'path' is omitted, the note is appended to the current day's log file (wiki/logs/YYYY-MM-DD.md).

Inputs: content (required), path, heading.

list_pagesB

Lists all the pages in the wiki (.md/.html files). Optionally accepts a subfolder.

Inputs: subdir.

read_pageB

Reads the content of a wiki page given the relative path (e.g. 'notes/example-note.md').

Inputs: path (required).

write_pageB

Creates or overwrites a wiki page. If the extension is missing .md is added.

Inputs: path (required), content (required), overwrite.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 5 tools

    Disambiguation4/5

    Each tool has a distinct purpose: listing, reading, searching, writing, and appending. write_page and append_note both modify content, but descriptions clearly differentiate full-page overwrite from quick log appends.

    Naming Consistency4/5

    Mostly consistent verb_noun pattern (list_pages, read_page, write_page, append_note), with 'search' being the lone bare-verb deviation. Still readable and predictable.

    Tool Count5/5

    Five tools is well-scoped for a simple wiki server, with each tool earning its place across discovery, reading, search, and content creation.

    Completeness3/5

    Covers list, read, search, create/overwrite, and append, but lacks a delete/remove_page operation and any rename/move capability, leaving a notable lifecycle gap for wiki maintenance.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for AI agents to read, write, and organize notes in a local-first, human-in-the-loop note-taking app.
      3 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A self-hosted Markdown knowledge base and Agent Harness with an MCP server that enables AI agents to read and write notes, providing persistent memory and a shared workspace for multi-agent collaboration.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A lightweight personal wiki MCP server that allows AI assistants to save, search, and link markdown notes with backlinks and full-text search, functioning as a file-based second brain.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for managing a local, domain-agnostic knowledge base using Markdown notes with frontmatter. Enables AI agents to capture, read, search, link, and maintain notes with atomic writes and privacy controls.
      13
      MIT