wiki-mcp

A fast, read-only Model Context Protocol (MCP) server for Karpathy-style LLM Markdown wikis.

Supports both Local Mode (stdio) and Remote Mode (Streamable HTTP, MCP 2.x standard) backed by a Git repository with automatic webhook synchronization.

The 3 Read-Only Tools

read_orientation(): Reads SCHEMA.md, index.md, and the last 30 lines of log.md in a single roundtrip.
search_wiki(query, tag=None): Fast full-text and taxonomy-tag search across curated wiki directories (concepts/, entities/, comparisons/, queries/).
get_page(slug_or_path): Safely reads any wiki page, cleanly parsing frontmatter YAML and markdown body.

Zero file mutation or deletion tools are exposed, guaranteeing your wiki's integrity.

Running in Local Mode (stdio)

Run directly against your local wiki using uv:

uv run --directory /Users/paolo/Projects/wiki-mcp wiki-mcp --wiki-dir /path/to/wiki

Local Client Config (`mcp_config.json`):

{
  "mcpServers": {
    "dev-wiki": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/paolo/Projects/wiki-mcp",
        "wiki-mcp",
        "--wiki-dir",
        "/path/to/wiki"
      ]
    }
  }
}

Running in Remote Mode (Streamable HTTP)

In Remote Mode, wiki-mcp runs as a centralized daemon on a server or Docker container. It clones/pulls the wiki Git repo on startup and listens for incoming IDE connections and GitHub/GitLab webhooks.

CLI Launch

uv run --directory /Users/paolo/Projects/wiki-mcp wiki-mcp   --remote   --host 0.0.0.0   --port 8000   --wiki-dir /data/wiki   --git-url "https://github.com/your-org/dev-wiki.git"   --auth-token "team-secret-token"   --webhook-secret "webhook-hmac-secret"

Environment Variables

Variable	Description	Default
`REMOTE_MODE`	Set to `true` or `1` for HTTP mode	`false`
`HOST`	Bind address	`0.0.0.0`
`PORT`	HTTP port	`8000`
`WIKI_PATH`	Local filesystem path to cache/clone wiki	Current directory
`WIKI_GIT_URL`	Git remote URL to clone if path is empty	`None`
`AUTH_TOKEN`	Bearer token required for `/mcp` endpoints	`None` (open)
`WIKI_WEBHOOK_SECRET`	Secret for verifying GitHub/GitLab webhooks	`None` (open)
`LOG_LEVEL`	Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`)	`INFO`

Remote Endpoints

POST /mcp: The core MCP Streamable HTTP endpoint. If AUTH_TOKEN is configured, requests must supply Authorization: Bearer <AUTH_TOKEN>.
GET /health: Public liveness and readiness probe for load balancers. Returns {"status": "healthy", "commit": "..."}.
POST /webhook: Inbound webhook for GitHub (X-Hub-Signature-256) and GitLab (X-Gitlab-Token). Automatically triggers git pull --ff-only on the local mirror.

Docker Deployment

Docker Compose

docker compose up -d

Docker Run

docker run -d \
  -p 8000:8000 \
  -v wiki-data:/data/wiki \
  -e WIKI_GIT_URL="https://github.com/your-org/dev-wiki.git" \
  -e AUTH_TOKEN="team-secret-token" \
  -e WIKI_WEBHOOK_SECRET="webhook-hmac-secret" \
  wiki-mcp:latest

Developer Client Setup (Remote)

Developers on your team point their IDE (Antigravity IDE, Cursor, Claude Desktop) to your centralized instance:

{
  "mcpServers": {
    "team-wiki": {
      "url": "https://wiki.internal.company.com/mcp",
      "headers": {
        "Authorization": "Bearer team-secret-token"
      }
    }
  }
}

Principles & Architecture

12-Factor XI (Logs): Treats logs as unbuffered structured JSON event streams to stdout.
12-Factor III (Config): Configuration driven strictly by environment variables.
Gall's Law & YAGNI: Starts from a simple, reliable core (shallow Git clone + FastMCP + webhook) without unnecessary database or caching bloat.
Wiki Principles (Ward Cunningham): Convergence over locking, soft security via read-only access, and transparent observability via Git commit history and log.md.