MCP Integration¶

Knowmarks exposes 27 tools via the Model Context Protocol (MCP), giving AI agents full CRUD access to your knowledge base.

Setup¶

Add to your Claude Desktop MCP configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "knowmarks": {
      "command": "km-mcp"
    }
  }
}

Add to your project's .mcp.json or global MCP config:

{
  "mcpServers": {
    "knowmarks": {
      "command": "km-mcp"
    }
  }
}

Any MCP-compatible client can connect using the km-mcp command with stdio transport.

Tool	Description
`search`	Hybrid semantic + keyword search with scoping (cluster, project, time)
`related`	Find items semantically related to a specific knowmark
`pulse`	Collection health briefing — recent activity, stale items, emerging topics
`stats`	Collection statistics (total items, breakdown by source)
`stale`	Items that may need governance attention

Tool	Description
`save`	Save a URL to the knowledge base
`get_knowmark`	Full details for a knowmark by ID
`update_note`	Update the note on a knowmark
`delete_knowmark`	Permanently delete a knowmark

Tool	Description
`list_projects`	List all projects with item counts
`get_project`	Project details including associated knowmarks
`create_project`	Create a project with context doc or metadata
`update_project`	Update project context or metadata
`add_to_project`	Pin a knowmark to a project
`remove_from_project`	Remove (dismiss) a knowmark from a project
`delete_project`	Delete a project
`refine`	LLM-assisted re-ranking of project associations

Tool	Description
`list_clusters`	List all topic clusters
`get_cluster`	Cluster members and keywords

Tool	Description
`list_collections`	List all curated collections
`get_collection`	Collection members
`create_collection`	Create a keyword-seeded collection
`delete_collection`	Delete a collection

Tool	Description
`reembed`	Re-embed knowmarks to refresh vector representations
`retry_fetch`	Retry content extraction for failed items
`rebuild_clusters_tool`	Force a full cluster rebuild
`connector_health`	Check connector sync status

Most tools support a detail parameter with three levels:

minimal — IDs and titles only. Best for orientation and listing.
summary (default) — Adds URLs, snippets, and key metadata. Good for most workflows.
full — Everything including content, explanations, and URLs. Use when you need complete information.

When a tool encounters an error, it returns a structured message:

Error [NOT_FOUND]: Knowmark 999 not found. Suggestion: Use search() to find items by keyword.

Error codes include NOT_FOUND, INVALID_INPUT, EMPTY_COLLECTION, NO_RESULTS, and REFINE_FAILED.

pulse() → search("topic") → get_knowmark(id)

pulse() → stale() → retry_fetch() or reembed() or rebuild_clusters()

list_projects() → get_project(id) → search("relevant topic") → add_to_project(proj_id, km_id)

search("topic", detail="full") → related(id) → get_knowmark(id)