Wiki MCP
README.md
# Wiki MCP ๐
[](https://github.com/Dreamernosleep/wiki-mcp/actions/workflows/ci.yml)
[](https://github.com/Dreamernosleep/wiki-mcp/releases)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](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>
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data