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

1. read_orientation(): Reads SCHEMA.md, index.md, and the last 30 lines of log.md in a single roundtrip.

2. search_wiki(query, tag=None): Fast full-text and taxonomy-tag search across curated wiki directories (concepts/, entities/, comparisons/, queries/).

3. 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.

Related MCP server: ai-wiki-mcp

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

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.