Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
/**
* MCP (Model Context Protocol) server for Trilium Notes.
*
* Exposes existing LLM tools via the MCP protocol so external AI agents
* (e.g. Claude Desktop) can interact with Trilium.
*/
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import { isToolErrorResult } from "@triliumnext/commons";
import { app_info as appInfo } from "@triliumnext/core";
import { cls } from "@triliumnext/core";
import { allToolRegistries, resolveToolRegistries } from "@triliumnext/core/src/services/llm/tools/index.js";
import type { ToolDefinition } from "@triliumnext/core/src/services/llm/tools/tool_registry.js";
import sql from "../sql.js";
/**
* Register a tool definition on the MCP server.
*
* Write operations are wrapped in CLS + transaction context so that
* Becca entity tracking works correctly. With `toolHints`, the annotations tell
* the client which tools only read and which overwrite or remove, so it can
* decide what to ask the user about.
*/
function registerTool(server: McpServer, name: string, def: ToolDefinition, toolHints: boolean) {
const annotations = def.mutates
? { readOnlyHint: false, destructiveHint: def.additive !== true, openWorldHint: false }
: { readOnlyHint: true, openWorldHint: false };
server.registerTool(name, {
description: def.description,
inputSchema: def.inputSchema,
annotations: toolHints ? annotations : undefined
}, (args: any): CallToolResult => {
const result = cls.init(() => {
cls.set("componentId", "mcp");
return def.mutates
? sql.transactional(() => def.execute(args))
: def.execute(args);
});
const content: CallToolResult["content"] = [{ type: "text", text: JSON.stringify(result) }];
// Without `isError`, an agent (and the chat behind it) takes a failure for a success.
return isToolErrorResult(result) ? { content, isError: true } : { content };
});
}
/**
* Build Trilium's MCP server. An in-chat agent's server sets `toolHints: false`: the chat's
* approvals decide its calls, and Codex runs a tool marked read-only without asking.
*/
export async function createMcpServer({ toolHints = true }: { toolHints?: boolean } = {}): Promise<McpServer> {
// Host-registered registries (the User Guide tools) load lazily; the array
// is complete only after this resolves.
await resolveToolRegistries();
const server = new McpServer({
name: "trilium-notes",
version: appInfo.appVersion
});
for (const registry of allToolRegistries) {
for (const [name, def] of registry) {
registerTool(server, name, def, toolHints);
}
}
return server;
}