MCP Server

Overview

Connect AI agents to your knowledge base

kazam includes an MCP (Model Context Protocol) server that lets AI agents read, search, and write pages in your site. It works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.

Tools exposed:

Tool	Description
`list_pages`	List all pages or a subdirectory
`read_page`	Read a page's YAML content and metadata
`search`	Text search across all page content
`get_config`	Read the site configuration
`write_page`	Create or update a page (requires `--allow-writes`)

Local setup

Stdio transport — single user

The default stdio transport runs locally. The agent spawns kazam as a child process and communicates over stdin/stdout.

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "my-site": {
      "command": "kazam",
      "args": ["mcp", "path/to/site"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "my-site": {
      "command": "kazam",
      "args": ["mcp", "/absolute/path/to/site"]
    }
  }
}

Enable writes

By default, write_page is disabled. To let agents create and edit pages:

kazam mcp path/to/site --allow-writes

Team setup

HTTP transport — serve your whole team

The HTTP transport serves the MCP protocol over the network. Anyone who can reach the endpoint can connect their AI tools to the shared knowledge base.

kazam mcp path/to/site --transport http --port 8090

This starts an HTTP server on port 8090 that accepts JSON-RPC POST requests with CORS support.

Production deployment

Run behind a reverse proxy for HTTPS. Example with Caddy:

# Caddyfile snippet
handle /brain/mcp {
    reverse_proxy localhost:8090
}

Create a systemd service so it starts on boot:

# /etc/systemd/system/kazam-mcp.service
[Unit]
Description=Kazam MCP Server
After=network.target

[Service]
ExecStart=/usr/local/bin/kazam mcp /opt/my-site --transport http --port 8090
Restart=on-failure

[Install]
WantedBy=multi-user.target

Connecting clients to the remote endpoint

Claude Code — add to .mcp.json using the proxy script (see below):

{
  "mcpServers": {
    "my-site": {
      "command": "python3",
      "args": ["path/to/mcp-proxy.py"]
    }
  }
}

Claude Desktop — same config in claude_desktop_config.json.

curl — test the endpoint directly:

curl -X POST https://your-host/brain/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Proxy script

Stdio-to-HTTP bridge for Claude Desktop

Claude Desktop only supports stdio-based MCP servers. This small Python script bridges stdio to your remote HTTP endpoint. Save it anywhere and point your Claude Desktop config at it.

No dependencies beyond Python 3 (pre-installed on macOS and most Linux).

#!/usr/bin/env python3
"""Stdio-to-HTTP proxy for a remote kazam MCP server."""
import sys, json, urllib.request

ENDPOINT = "https://your-host.example.com/brain/mcp"  # ← change this

while True:
    line = sys.stdin.readline()
    if not line:
        break
    line = line.strip()
    if not line:
        continue
    try:
        parsed = json.loads(line)
    except json.JSONDecodeError:
        continue

    is_notification = parsed.get("method", "").startswith("notifications/")
    try:
        req = urllib.request.Request(
            ENDPOINT,
            data=line.encode("utf-8"),
            headers={"Content-Type": "application/json"},
            method="POST",
        )
        with urllib.request.urlopen(req) as resp:
            response = resp.read().decode("utf-8").strip()
        if not is_notification and response:
            sys.stdout.write(response + "\n")
            sys.stdout.flush()
    except Exception as e:
        if not is_notification and "id" in parsed:
            err = json.dumps({
                "jsonrpc": "2.0",
                "id": parsed["id"],
                "error": {"code": -32603, "message": str(e)},
            })
            sys.stdout.write(err + "\n")
            sys.stdout.flush()

Setup for non-technical users:

Save the script above as mcp-proxy.py (change the ENDPOINT URL)
Open Claude Desktop → Settings → Developer → Edit Config
Add the mcpServers entry pointing at the script
Restart Claude Desktop
Start a new conversation — the MCP tools appear automatically

Reference

CLI flags

Flag	Default	Description
`--transport`	`stdio`	Transport protocol: `stdio` or `http`
`--port`	`8080`	Port for HTTP transport
`--allow-writes`	off	Enable the `write_page` tool