Content
# wiki-search-mcp
[](https://badge.fury.io/py/wiki-search-mcp)
[](https://pypi.org/project/wiki-search-mcp/)
[](https://pypi.org/project/wiki-search-mcp/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/jin7942/wiki-search-mcp/stargazers)
[](https://github.com/jin7942/wiki-search-mcp/issues)
[](https://github.com/jin7942/wiki-search-mcp/commits)
[](https://github.com/astral-sh/ruff)
**Zero-config Personal Knowledge Management(PKM) MCP Server** — Automatically categorize, search, and organize your local Markdown notes. No configuration file required. Preserves your folder structure.
## Features
- **Zero-Config**: No configuration file required. Use any directory as is.
- **Automatic Categorization**: Detect uncategorized files → Analyze content → Suggest categories/tags → Automatic organization.
- **Automatic Category Detection**: User folder structure becomes categories (no manual definition required).
- **Hybrid Search**: Vector (sentence-transformers) + BM25 keyword combination (RRF), optimized for Korean.
- **Graph RAG**: Automatically expand related documents through wikilink `[[link]]` relationships.
- **Local Execution**: All processing occurs locally, without external APIs (zero cost).
- **Read-only MCP**: All tools are read-only. File writing is handled by Claude's general tools.
## Quick Start
```bash
# 1. Installation
pipx install wiki-search-mcp
# 2. Register Claude Desktop (any directory)
wiki-search-mcp config ~/my-notes
# 3. Restart Claude Desktop
```
Point to an empty or existing note directory. The index is automatically generated on the first search, and a watcher detects changes thereafter.
## v0.2.0 — Automatic Categorization Daemon (optional)
Introduced a background daemon that categorizes newly written `.md` files without user intervention and moves them to category folders. Runs even when Claude Desktop is shut down.
```bash
# 0. (One-time) Claude subscription login — Reuse OAuth without API key registration
claude login
# 1. Start daemon — Omit path to use registered config info (v0.2.1+)
wiki-search-mcp daemon start
# 2. Status/logs
wiki-search-mcp daemon status
wiki-search-mcp daemon logs -f
# 3. Revert changes
wiki-search-mcp daemon rollback --last 5 --dry-run
# 4. Stop
wiki-search-mcp daemon stop
```
> You can specify a path explicitly using the `daemon <command> <path>` format (when using multiple wikis).
- Authentication: Reuses the paid Claude Pro/Max subscription (no Anthropic API key registration required).
- Reliability: Records applied changes in `applied.jsonl` → Can revert with `daemon rollback`.
- Safety: Never overwrites user-written frontmatter fields (preserves user values).
- Rate limiting: Default sliding window of 5/min, 100/hour, 500/day. Adjustable with `--rate-per-*` options.
## Table of Contents
- [Quick Start](#quick-start)
- [Features](#features)
- [How are categories determined?](#how-are-categories-determined)
- [MCP Tools](#mcp-tools)
- [CLI Commands](#cli-commands)
- [Configuration](#configuration)
- [Ignore Patterns](#ignore-patterns)
- [File Watching](#file-watching)
- [Troubleshooting](#troubleshooting)
- [Documentation](#documentation)
- [License](#license)
## How are categories determined?
No configuration file is created. Categories are determined in the following order of priority:
1. **Automatic User Folder Detection**: If there are ≥ 2 subdirectories under the note root (or `pages/`), their names become categories.
2. **AI Suggestion Fallback**: If there are no or only one category, Claude analyzes the index and suggests candidates.
```text
~/my-notes/
├── work/ ← Category "work"
├── personal/ ← Category "personal"
├── infra/ ← Category "infra"
└── memo.md ← Waiting for categorization (Claude suggests organization)
```
## MCP Tools
A total of 16 tools. **All are read-only** — File writing is handled by the daemon (optional) or Claude's general tools.
| Category | Tool | Description |
|------|------|------|
| Search | `wiki_search` | Hybrid (vector + keyword) search + graph expansion |
| Search | `wiki_get_similar` | Similar document recommendation |
| Search | `wiki_get_backlinks` | Backlink inquiry |
| Search | `wiki_find_orphans` | Orphan document exploration |
| Inquiry | `wiki_get_document` | Document detailed inquiry |
| Inquiry | `wiki_list_documents` | Category/tag/state-based lists |
| Inquiry | `wiki_stats` | Overall statistics |
| Categorization | `wiki_get_categories` | Automatic folder detection categories |
| Categorization | `wiki_suggest_categories` | AI category candidate suggestions |
| Categorization | `wiki_pending` | Uncategorized / waiting for organization files |
| Categorization | `wiki_suggest_classification` | Single file categorization recommendation |
| Categorization | `wiki_suggest_tags` | Automatic tag extraction |
| Management | `wiki_reindex` | Index rebuilding |
| Management | `wiki_watch_status` | File watching status |
| Management | `wiki_daemon_status` | Automatic categorization daemon status (v0.2.0) |
| Management | `wiki_validate` | Frontmatter / wikilink validation |
Detailed usage: [API Reference](docs/API.md)
## Requirements
- Python 3.9+
- ~500MB disk (embedding model cache)
## CLI Commands
### `config <path>`
Registers the MCP server with Claude Desktop.
```bash
wiki-search-mcp config ~/my-notes
```
Automatically added to `~/.claude/claude_desktop_config.json`.
### `index <path>`
Manual indexing. MCP server automatically indexes on start/change, so this is usually unnecessary.
```bash
wiki-search-mcp index ~/my-notes # Incremental update
wiki-search-mcp index ~/my-notes --full # Full rebuild
```
### `serve <path>`
Run the MCP server directly (for debugging).
```bash
wiki-search-mcp serve ~/my-notes
wiki-search-mcp serve ~/my-notes --log-level DEBUG --no-watch
```
### `daemon <subcommand> [path]` (v0.2.0+)
Background automatic categorization daemon. Reuses `claude login` OAuth, so no separate API key registration is required.
**Path argument is optional.** Omit it to automatically use the wiki-search server's path registered with `wiki-search-mcp config`. Only specify the argument explicitly if you are using multiple wikis.
```bash
wiki-search-mcp daemon start # Start in background (automatic path detection)
wiki-search-mcp daemon start --foreground # For debugging
wiki-search-mcp daemon status # JSON status
wiki-search-mcp daemon logs -f # Log tail
wiki-search-mcp daemon stop # SIGTERM → 10 seconds later SIGKILL
wiki-search-mcp daemon rollback --last 5 # Revert last 5 changes
# Explicit path specification is also possible
wiki-search-mcp daemon start ~/another-vault
```
Main options (start):
- ``--confidence-threshold 0.7`` Automatic application threshold
- ``--rate-per-minute 5 --rate-per-hour 100 --rate-per-day 500`` Rate limiting
- ``--concurrency 2`` Concurrent worker count
- ``--llm-model haiku`` Claude model alias
- ``--no-auto-move`` Disable category folder movement
## Configuration
**No environment variables.** All settings are passed as CLI positional arguments/flags. The `config` command serializes options directly into the `args` array of `claude_desktop_config.json`.
### CLI Options (`serve` / `config` shared)
| Option | Description | Default |
|------|------|--------|
| `<path>` | Note root path (positional argument, required) | — |
| `--model NAME` | Embedding model preset (`fast`/`accurate`) or model name | `accurate` |
| `--ignore PATTERN` | Additional ignore pattern (repeatable) | (none) |
| `--no-watch` | Disable file watching | (watching enabled) |
| `--debounce SECONDS` | Watch debounce (seconds) | `2.0` |
| `--log-level LEVEL` | `DEBUG`/`INFO`/`WARNING`/`ERROR` | `WARNING` |
| `--log-file PATH` | Log file path | (stderr only) |
### Embedding Models
| Preset | Model | Characteristics |
|--------|------|------|
| `fast` | `all-MiniLM-L6-v2` | Fast, English optimized |
| `accurate` | `ko-sroberta-multitask` | Accurate, Korean optimized (default) |
### Manual Setup
If you prefer to set up manually instead of using the CLI, create `~/.claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"wiki-search": {
"command": "wiki-search-mcp",
"args": ["serve", "/absolute/path/to/your/notes"]
}
}
}
```
Add options by appending to the `args` array:
```json
"args": ["serve", "/abs/path", "--model", "fast", "--no-watch"]
```
Or generate it with a single command:
```bash
wiki-search-mcp config <path> --model fast --no-watch
```
## Ignore Patterns
No configuration file is used. Ignore targets are determined by the following three methods:
1. **Automatic**: Directories/files starting with a dot (`.git`, `.obsidian`, `.vectordb`, `.DS_Store`, etc.)
2. **`.gitignore` automatic utilization**: If `.gitignore` exists in the note root, patterns are applied
3. **`--ignore` option**: Repeatable specification via CLI
```bash
wiki-search-mcp serve ~/notes --ignore "draft" --ignore "*.bak" --ignore "private"
```
## File Watching
The MCP server automatically watches the note directory when running.
- `.md` files added/modified/deleted are automatically index updated
- Debounce: Continuous changes are processed 2 seconds after the last change
- Disabled: `--no-watch`
```bash
wiki-search-mcp serve ~/notes --no-watch # Disable watching
wiki-search-mcp serve ~/notes --debounce 5.0 # Debounce 5 seconds
```
## Troubleshooting
### Slow model download
Downloads the embedding model (~400MB) on the first run. Setting a HuggingFace token makes it faster.
```bash
export HF_TOKEN=your_huggingface_token
```
### Indexing not working
```bash
wiki-search-mcp index ~/my-notes --full
```
### MCP server not connecting
```bash
# Run directly to check for errors
wiki-search-mcp serve ~/my-notes --log-level DEBUG
```
## Documentation
| Document | Description |
|------|------|
| [API Reference](docs/API.md) | Detailed usage of MCP tools (16) |
| [Performance Tuning](docs/PERFORMANCE.md) | Large-scale note optimization |
| [Writing Guide](docs/WRITING.md) | Frontmatter, State, Confidence |
| [Installation Guide](docs/INSTALLATION.md) | Scenario-based detailed installation |
## License
MIT License
