Skip to main content
Glama
README.md
# Wiki MCP ๐Ÿš€

[![CI](https://github.com/Dreamernosleep/wiki-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Dreamernosleep/wiki-mcp/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/Dreamernosleep/wiki-mcp?label=release)](https://github.com/Dreamernosleep/wiki-mcp/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)

> **An open-source company knowledge wiki with AI superpowers.**
> Markdown files + Smart search + MCP server + Web UI + Docker

Wiki MCP is a self-hosted knowledge base that combines the simplicity of **Markdown files** with the power of **AI agents** through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). Your wiki is just a folder of `.md` files โ€” git-friendly, portable, and yours forever.

## โœจ Features

| Feature | Description |
|---------|-------------|
| ๐Ÿ“ **Markdown Files** | Your wiki is just `.md` files with YAML frontmatter โ€” edit in any editor! |
| ๐Ÿค– **MCP Server** | AI agents (Claude, pi, Cursor, etc.) can read, write, and search your wiki |
| ๐Ÿ” **Smart Search** | Typo-tolerant search with [Meilisearch](https://www.meilisearch.com/) (fallback: SQLite FTS5) |
| ๐ŸŒ **Web UI** | Clean black-and-white UI built with React + [shadcn/ui](https://ui.shadcn.com) โ€” visual (WYSIWYG) editor that saves plain Markdown, Markdown source mode with live preview, light/dark |
| ๐Ÿ”— **Wiki Links** | `[[page-slug]]` or `[[category/page-slug]]` with autocomplete while typing |
| ๐Ÿ“‚ **Dynamic Categories** | Create custom folders (categories) on the fly โ€” the install starts you with companies/contacts/accounts/services |
| ๐Ÿณ **Docker Ready** | One command to run everything: `docker compose up -d` |
| ๐Ÿ‘€ **File Watcher** | Edit files in VS Code/Obsidian โ€” changes auto-sync to search index |
| ๐Ÿ“Š **Graph View** | See how pages connect with a full link graph |
| ๐Ÿ”„ **Dual Transport** | MCP over stdio (local) or Streamable HTTP (Docker/remote) |

## ๐Ÿ—๏ธ Architecture

```
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                     docker compose up                    โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚ Meilisearch โ”‚  โ”‚  Wiki API   โ”‚  โ”‚    Web UI       โ”‚  โ”‚
โ”‚  โ”‚  (search)   โ”‚โ—„โ”€โ”‚  (MCP+REST) โ”‚โ—„โ”€โ”‚   (browser)     โ”‚  โ”‚
โ”‚  โ”‚  :7700      โ”‚  โ”‚  :3000      โ”‚  โ”‚   :80           โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚                          โ”‚                               โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚  Volumes: content/ (markdown), data/ (SQLite)     โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
         โ†‘                              โ†‘
    ๐Ÿค– AI Agents (MCP)            ๐Ÿ‘ค Humans (Browser)
    pi, Claude, Cursor...         View & Edit
```

## ๐Ÿš€ Quick Start

### Option 1: One-line install (Recommended)

The only prerequisite is [Docker](https://docs.docker.com/get-docker/). No Node, no git.

```bash
curl -fsSL https://raw.githubusercontent.com/Dreamernosleep/wiki-mcp/main/setup.sh | bash
```

This downloads the project into `./wiki-mcp`, creates your `.env`, generates a search-engine
password, starts everything with Docker Compose, and prints the URLs plus an MCP config block to
paste into your AI tool. Piped into `bash` it uses the defaults (UI on 80, API on 3000); to be
asked for the ports instead, run `bash <(curl -fsSL https://raw.githubusercontent.com/Dreamernosleep/wiki-mcp/main/setup.sh)`.

Already have a clone? Run `./setup.sh` from the repository root (`./setup.sh --yes` for no
prompts, `--no-start` to configure only). Re-running it is safe: existing `.env` values are kept.

> **Windows:** run the installer inside WSL or Git Bash (Docker Desktop for Windows installs WSL).

### Option 1b: Plain Docker Compose

```bash
git clone https://github.com/Dreamernosleep/wiki-mcp.git
cd wiki-mcp
cp .env.example .env     # optional: edit ports and MEILISEARCH_KEY
docker compose up -d     # Meilisearch + API + Web UI

# Open http://localhost in your browser!
```

> **About Meilisearch:** it is an open-source search engine that runs as a local container here.
> No account, no external service, no cost. `MEILISEARCH_KEY` is simply a password that locks your
> own instance. If the container is unavailable the wiki falls back to SQLite full-text search.

### Option 2: Local Development

```bash
# Prerequisites: Node.js 22+, Docker (for Meilisearch)

# Install dependencies
npm install

# Start Meilisearch
docker run -d -p 7700:7700 getmeili/meilisearch

# Run the API in development mode (http://localhost:3000)
npm run dev

# In a second terminal, run the web UI (http://localhost:5173, proxies /api to :3000)
cd ui && npm install && npm run dev
```

### Option 3: MCP Only (for AI agents)

```bash
npm install && npm run build

# Run as MCP server (stdio)
MCP_TRANSPORT=stdio node dist/server.js
```

## ๐Ÿ”Œ Connect AI Agents

### pi / Claude Desktop (Local)

```json
{
  "mcpServers": {
    "wiki": {
      "command": "node",
      "args": ["/path/to/wiki-mcp/dist/server.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "MEILISEARCH_URL": "http://localhost:7700"
      }
    }
  }
}
```

### Claude Code / Cursor / Remote Agents (HTTP)

```json
{
  "mcpServers": {
    "wiki": {
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

## ๐Ÿ› ๏ธ MCP Tools (18)

| Tool | Description |
|------|-------------|
| `list_categories` | List all wiki categories |
| `create_category` | Create a new category (folder) |
| `update_category` | Rename a category (display name, description) |
| `delete_category` | Delete a category; with `force`, its pages too |
| `create_page` | Create a new page (from markdown, or from a template) |
| `get_page` | Get a page by category/slug |
| `update_page` | Update a page's content |
| `delete_page` | Delete a page |
| `list_pages` | List all pages (filter by category) |
| `search_pages` | Smart search (typo-tolerant, ranked), optionally inside one category |
| `get_linked_pages` | Get pages linked to/from a page |
| `get_graph` | Get the full link graph |
| `sync_files` | Force sync from markdown files |
| `list_templates` | List page templates |
| `get_template` | Get a template with its markdown body |
| `create_template` | Create a reusable page template |
| `update_template` | Update a template's name, category, default flag or body |
| `delete_template` | Delete a template |

## ๐ŸŒ REST API

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/categories` | List categories |
| `POST` | `/api/categories` | Create category |
| `PUT` | `/api/categories/:id` | Rename a category (`name`, `description`) |
| `DELETE` | `/api/categories/:id` | Delete a category (`?force=true` deletes its pages too) |
| `GET` | `/api/pages` | List pages (`?category=companies`) |
| `GET` | `/api/pages/:category/:slug` | Get a page |
| `POST` | `/api/pages` | Create a page (`content`, or `template` id) |
| `PUT` | `/api/pages/:category/:slug` | Update a page |
| `DELETE` | `/api/pages/:category/:slug` | Delete a page |
| `GET` | `/api/search?q=...` | Search pages (optional `&category=companies` to search one folder) |
| `GET` | `/api/search/suggest?q=...` | Autocomplete suggestions |
| `GET` | `/api/graph` | Get link graph |
| `GET` | `/api/pages/:cat/:slug/links` | Get linked pages |
| `POST` | `/api/sync` | Force file sync |
| `GET` | `/api/raw/:category/:slug` | Get raw markdown |
| `GET` | `/api/templates` | List page templates |
| `GET` | `/api/templates/:id` | Get a template |
| `POST` | `/api/templates` | Create a template |
| `PUT` | `/api/templates/:id` | Update a template |
| `DELETE` | `/api/templates/:id` | Delete a template |
| `GET` | `/health` | Health check |

## ๐Ÿ“ Project Structure

```
wiki-mcp/
โ”œโ”€โ”€ .github/                # GitHub Actions, issue templates
โ”œโ”€โ”€ src/
โ”‚   โ”œโ”€โ”€ server.ts           # MCP + REST API server
โ”‚   โ”œโ”€โ”€ db.ts               # SQLite (graph, metadata)
โ”‚   โ”œโ”€โ”€ files.ts            # Markdown file I/O
โ”‚   โ”œโ”€โ”€ search.ts           # Meilisearch client
โ”‚   โ”œโ”€โ”€ watcher.ts          # File watcher (auto-sync)
โ”‚   โ””โ”€โ”€ sync.ts             # Manual sync script
โ”œโ”€โ”€ ui/                     # Web UI (Vite + React + shadcn/ui)
โ”‚   โ”œโ”€โ”€ src/
โ”‚   โ”‚   โ”œโ”€โ”€ App.tsx         # App state and layout
โ”‚   โ”‚   โ”œโ”€โ”€ components/     # Sidebar, editor, preview, dialogs (+ ui/ from shadcn)
โ”‚   โ”‚   โ”œโ”€โ”€ lib/            # API client, markdown rendering
โ”‚   โ”‚   โ””โ”€โ”€ styles/
โ”‚   โ”‚       โ”œโ”€โ”€ brand.css   # โ˜… All colours, radius, fonts โ€” edit to re-theme
โ”‚   โ”‚       โ””โ”€โ”€ index.css   # Tailwind + token mapping
โ”‚   โ”œโ”€โ”€ BRANDING.md         # How to change colours / name
โ”‚   โ”œโ”€โ”€ Dockerfile          # Builds the bundle, serves it with nginx
โ”‚   โ””โ”€โ”€ nginx.conf.template # Serves the app and proxies /api to the API
โ”œโ”€โ”€ content/                # Your wiki (markdown files; gitignored, created on first start)
โ”‚   โ”œโ”€โ”€ _templates/         # Page templates (see below)
โ”‚   โ”œโ”€โ”€ companies/          # One page per client organization
โ”‚   โ”œโ”€โ”€ contacts/           # People at those companies
โ”‚   โ”œโ”€โ”€ accounts/           # Engagements: status, services, timeline
โ”‚   โ”œโ”€โ”€ services/           # Your service catalog
โ”‚   โ””โ”€โ”€ engineering/        # Custom categories!
โ”œโ”€โ”€ data/                   # SQLite database
โ”œโ”€โ”€ docker-compose.yml      # One-command setup
โ”œโ”€โ”€ Dockerfile              # Wiki API container
โ””โ”€โ”€ README.md
```

## ๐Ÿ“ Markdown Format

Pages are stored as markdown files with YAML frontmatter:

```markdown
---
id: abc123-uuid
category: companies
slug: acme
title: Acme Inc
created: 2026-10-27
updated: 2026-10-27
created_by: agent
---

# Acme Inc

## Contacts
- [[contacts/jane-doe]] โ€” CEO

## Accounts
- [[accounts/acme-website-redesign]] โ€” active
```

## ๐Ÿ“‹ Page Templates

Templates keep pages of the same kind (a company, a contact, meeting notes) in the same shape, whether a person creates them in the web UI or an agent creates them over MCP. A template is a markdown file in `content/_templates/`:

```markdown
---
name: Company profile
description: One page per client organization
category: companies      # optional: the category this template belongs to
default: true            # optional: preselected for new pages in that category
---
# {{title}}

## Overview
- Domain:
- Industry:
```

- `{{title}}`, `{{category}}` and `{{date}}` are filled in when a page is created from the template.
- A template with a `category` is offered for that category; without one it is general purpose. Only one template per category can be `default`; setting a new default clears the previous one.
- The install ships a CRM-style starter kit: four categories (**Companies**, **Contacts**, **Accounts**, **Services**), each with a default template (**Company profile**, **Contact card**, **Account**, **Service**) that links records together with `[[category/slug]]`, plus three general templates (**Procedure**, **Meeting notes**, **Decision record**). Categories and templates are written on first start only; rename, edit or delete them freely.
- In the web UI, the New page dialog has a Template picker, and any open page can be saved as a template (the page heading becomes `{{title}}`).
- Agents: `list_templates` shows what exists, `create_page` accepts a `template` id (and falls back to the category default when `content` is omitted), and `create_template` / `update_template` / `delete_template` manage them.

## ๐Ÿ”— Wiki Links

Link pages with `[[slug]]` or `[[category/slug]]`:

```markdown
See [[acme]] for details.
Or use full path: [[companies/acme]]
```

## ๐ŸŽจ Theming the Web UI

The UI ships black-and-white with a light/dark toggle. Every colour, the corner radius and the fonts
live in **one file**: [`ui/src/styles/brand.css`](ui/src/styles/brand.css). Change `--primary` there
and every button, active row, focus ring and link follows. See [`ui/BRANDING.md`](ui/BRANDING.md)
for a walkthrough, including how to set a brand colour instead of black.

## ๐Ÿงช Development

```bash
# Run tests
npm test

# Test MCP client
npm run test:mcp

# Manual sync (rebuild DB from files)
npm run sync

# Docker commands
npm run docker:build
npm run docker:up
npm run docker:down
npm run docker:logs
```

## ๐Ÿค Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

- ๐Ÿ› [Report a Bug](.github/ISSUE_TEMPLATE/bug_report.md)
- ๐Ÿ’ก [Request a Feature](.github/ISSUE_TEMPLATE/feature_request.md)
- ๐Ÿ”’ [Security Policy](SECURITY.md)
- ๐Ÿ“œ [Code of Conduct](CODE_OF_CONDUCT.md)

## ๐Ÿ“œ License

This project is licensed under the [MIT License](LICENSE) โ€” see the LICENSE file for details.

## ๐Ÿ™ Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io/) โ€” AI agent integration
- [Meilisearch](https://www.meilisearch.com/) โ€” Smart search engine
- [shadcn/ui](https://ui.shadcn.com/) + [Tailwind CSS](https://tailwindcss.com/) โ€” Web UI components
- [Marked.js](https://marked.js.org/) โ€” Markdown rendering
- [Chokidar](https://github.com/paulmillr/chokidar) โ€” File watching
- [node:sqlite](https://nodejs.org/api/sqlite.html) โ€” Database

---

<p align="center">
  Made with โค๏ธ for the open source community
</p>

<p align="center">
  <a href="https://github.com/Dreamernosleep/wiki-mcp">โญ Star us on GitHub</a>
</p>