MCP (Model Context Protocol)

KiwiFS ships a built-in MCP server so agents can work with the same operations as the REST API and web UI.

Start the MCP server

# In-process (reads files directly, no HTTP server required)
kiwifs mcp --root ~/knowledge

# Proxy mode (forwards to a running KiwiFS server)
kiwifs mcp --remote http://host:3333 --api-key kiwi_sk_...

# Streamable HTTP transport (remote agents, LAN tools)
kiwifs mcp --root ~/knowledge --http --port 8181

# Streamable HTTP on the main server port (no separate process)
kiwifs serve --root ~/knowledge --mcp

Use --space <name> when the knowledge root hosts multiple configured spaces. Remote HTTP MCP should stay behind TLS and reuse the same API keys you trust for REST.

The --mcp flag on kiwifs serve mounts the MCP endpoint at /mcp on the main HTTP server, so agents can reach both REST and MCP on the same port.

Configure Claude Desktop / Cursor

{
  "mcpServers": {
    "kiwifs": {
      "command": "kiwifs",
      "args": ["mcp", "--root", "/path/to/knowledge"]
    }
  }
}

Tool inventory

The server currently registers 68+ tools (exact count may change release to release). They are grouped below; every name is invoked as listed.

Core files and search

Tool	Summary
`kiwi_read`	Read markdown with optional wiki-link resolution, metadata-only mode, and `if_not_etag` caching.
`kiwi_write`	Create/update a page (git-versioned) with optional `actor` and `provenance`.
`kiwi_delete`	Delete a path (history preserved when git versioning is on).
`kiwi_rename`	Move/rename with optional wiki-link rewrites across the tree.
`kiwi_bulk_write`	Atomic multi-file commit.
`kiwi_append`	Append without read-modify-write races.
`kiwi_tree`	Directory listing with depth and optional permalinks.
`kiwi_search`	BM25 full-text search with pagination and `path_prefix`.
`kiwi_search_semantic`	Vector similarity search (requires embeddings).
`kiwi_changes`	Incremental change list since a checkpoint.
`kiwi_versions`	Git history entries for a path.
`kiwi_view_refresh`	Regenerate a computed `kiwi-view` markdown file.

Metadata, DQL, and analytics

Tool	Summary
`kiwi_query_meta`	Frontmatter filters with AND/OR groups, sort, pagination.
`kiwi_query`	DQL queries (`TABLE`, `LIST`, `COUNT`, `DISTINCT`, …).
`kiwi_aggregate`	`GROUP BY` style aggregates over metadata.
`kiwi_import`	Pull from databases, CSV/JSON, Notion, Airtable, etc.
`kiwi_export`	Export JSONL/CSV with optional embeddings.
`kiwi_analytics`	Knowledge-base health metrics.
`kiwi_health_check`	Single-page diagnostics.
`kiwi_memory_report`	Episodic memory coverage / merge hints.
`kiwi_velocity`	Change hotspots, cold pages, bursts.
`kiwi_eval`	Search quality benchmark harness.
`kiwi_context`	Schema, playbook, index, and rules in one call — good first tool.
`kiwi_backlinks`	Incoming wiki links for a page.
`kiwi_suggestions`	Semantically similar pages excluding existing links.
`kiwi_embeddings`	Raw chunk embeddings for a page.
`kiwi_graph_analytics`	PageRank-ish graph summary.
`kiwi_graph_centrality`	PageRank and betweenness tables.
`kiwi_graph_communities`	Louvain communities.
`kiwi_graph_path`	Shortest path between two pages.
`kiwi_graph_walk`	Local neighborhood / siblings around a page.
`kiwi_eligible`	Ranked todo-style tasks inferred via metadata heuristics.

Draft spaces

Tool	Summary
`kiwi_draft_create`	Open a new git-backed draft branch.
`kiwi_draft_list`	List active drafts.
`kiwi_draft_read` / `kiwi_draft_write`	Work inside a draft by `draft_id`.
`kiwi_draft_diff`	Unified diff vs main.
`kiwi_draft_merge`	Merge draft into live knowledge.
`kiwi_draft_discard`	Drop the draft branch.

Bases (saved views)

Tool	Summary
`kiwi_views_list`	List `.kiwi/views/*.json` definitions.
`kiwi_views_get`	Fetch a single view definition.
`kiwi_views_save`	Persist columns, filters, sort, layout, and query.
`kiwi_views_delete`	Remove a saved view.
`kiwi_views_execute`	Run the DQL backing a view and return rows.

Canvas

Tool	Summary
`kiwi_canvas_list`	Discover `*.canvas.json` files.
`kiwi_canvas_read` / `kiwi_canvas_write`	JSON canvas payloads.

Canvas generate, patch, query, and auto-layout are REST-only — see Canvas API.

Workflows and coordination

Tool	Summary
`kiwi_workflow_list` / `kiwi_workflow_get` / `kiwi_workflow_save`	Manage `.kiwi/workflows/*.json`.
`kiwi_workflow_advance`	Validate and apply a frontmatter state transition.
`kiwi_workflow_board`	Kanban-style board grouped by `state`.
`kiwi_claim` / `kiwi_release`	Cooperative leases on paths (requires actor headers in practice).
`kiwi_claims_list`	Inspect active claims.

Task orchestration

Tool	Summary
`kiwi_task_create`	Create a new task page with structured frontmatter and workflow state.
`kiwi_task_progress`	Append a timestamped progress entry to a task page.
`kiwi_cite`	Generate a citation reference for a source or paper.

Memory

Tool	Summary
`kiwi_remember`	Save an episodic observation to `episodes/{date}/{uuid}.md`.
`kiwi_forget`	Mark an episode as superseded (`memory_status: superseded`).

Content helpers and feeds

Tool	Summary
`kiwi_peek`	Lightweight summary (title, snippet, links, headings).
`kiwi_section`	Extract a single heading section by name or index.
`kiwi_timeline`	Recent git-backed activity with pagination metadata.
`kiwi_feed`	Serialized activity feed (JSON or Atom depending on mode).
`kiwi_clip`	Fetch a URL and persist clipped markdown.
`kiwi_ingest`	Convert supported binary documents to markdown via MarkItDown.
`kiwi_export_document`	Render markdown to PDF, HTML, slides, or a static site.
`kiwi_lint`	Structural markdown lint for a path or inline content.
`kiwi_eval`	Benchmark full-text and semantic search quality.

Resources

Read-only MCP resources:

URI pattern	Description
`kiwi://schema`	`SCHEMA.md` (or generated schema) for the knowledge root.
`kiwi://file/{path}`	Markdown bytes for a relative path.
`kiwi://tree/{path}`	Directory listing rooted at `{path}`.

Getting Started

Core Concepts

Guides

Data Import

Data Export

Deployment

Start the MCP server

Configure Claude Desktop / Cursor

Tool inventory

Resources

Further reading

​Start the MCP server

​Configure Claude Desktop / Cursor

​Tool inventory

​Resources

​Further reading

Start the MCP server

Configure Claude Desktop / Cursor

Tool inventory

Resources

Further reading