Claude Code

Claude Code is Anthropic's terminal-native coding agent. It implements MCP out of the box, which means wiring Korely is a few lines of JSON and a restart.

After this guide, Claude Code can search your notes, read full documents, traverse the knowledge graph, save new notes, and create tasks — without you leaving the terminal.

Prerequisites

• Claude Code installed. If you haven't, follow Anthropic's official quickstart. Korely doesn't depend on a specific Claude Code version — anything MCP-capable (1.0+) works.
• Korely installed with a vault at ~/Korely (or another path you'll point at). See the Quickstart if you haven't.
• Node 18+ on your PATH (for the npx command). Verify with node --version.

1. Locate the MCP config file

Claude Code reads its MCP server list from a single JSON file. The path depends on your OS:

If the file doesn't exist yet, create it with an empty object as starting point:

mkdir -p ~/.config/claude-code
echo '' > ~/.config/claude-code/mcp.json

2. Add the Korely server config

Open mcp.json in your editor of choice and add the korely entry under mcpServers:

{
  "mcpServers": {
    "korely": {
      "command": "npx",
      "args": ["-y", "@korely/mcp-server"],
      "env": {
        "KORELY_VAULT_ROOT": "~/Korely"
      }
    }
  }
}

KORELY_VAULT_ROOT is the absolute path (tilde-expanded) to your vault directory. Change it to match your setup — for example /Users/me/Documents/Notes if you already have an Obsidian vault you want Korely to read.

3. Restart Claude Code

Quit Claude Code completely. On macOS that's Cmd-Q, not just closing the window. On Linux/Windows quit from the terminal session and relaunch with claude-code.

On next launch, Claude Code spawns the Korely MCP server as a child process. Server startup is around 200ms — you won't notice it.

4. Verify the tools are exposed

Inside Claude Code, type /tools to list available tools. You should see the 7 Korely tools under the korely namespace:

korely_search
korely_read_item
korely_list_notes
korely_list_folders
korely_get_related
korely_save_note
korely_create_task

Smoke test with a natural-language query:

"Search my vault for any note that mentions 'roadmap'."

Claude Code should call korely_search, surface the matching snippets, and cite the source file paths. If your vault is empty it returns no hits — that's still a success, the wiring is working.

Common issues

"Tool korely_search not found"

Claude Code didn't load the server. Three things to check:

1. The JSON is valid — paste it into jq '.' < mcp.json; if jq fails, you have a syntax error. Trailing commas are the most common cause.
2. You actually quit and relaunched. Claude Code does not hot-reload MCP config.
3. Check the MCP log at ~/.config/claude-code/logs/mcp.log. Server startup errors show up there.

"npx: command not found" in the MCP log

Node isn't on Claude Code's PATH. The fix is to use the absolute path to npx in the config:

{
  "command": "/usr/local/bin/npx",
  "args": ["-y", "@korely/mcp-server"]
}

Find your npx path with which npx in any terminal where Node works.

"Vault path does not exist"

The path in KORELY_VAULT_ROOT doesn't resolve. Korely expects an absolute path or a tilde-prefixed home path. Common mistakes:

• Relative path like ./Korely — won't resolve, use absolute.
• Path with spaces unquoted — wrap in JSON-escaped quotes.
• Path doesn't exist yet — create the directory first: mkdir -p ~/Korely.

Power user tips

Multiple vaults

You can declare more than one Korely instance with different vaults. Useful if you keep work and personal vaults separate:

{
  "mcpServers": {
    "korely-work": {
      "command": "npx",
      "args": ["-y", "@korely/mcp-server"],
      "env": { "KORELY_VAULT_ROOT": "~/Vaults/Work" }
    },
    "korely-personal": {
      "command": "npx",
      "args": ["-y", "@korely/mcp-server"],
      "env": { "KORELY_VAULT_ROOT": "~/Vaults/Personal" }
    }
  }
}

Tools then namespace under each server name — korely-work_search, korely-personal_search, etc.

Pin a specific MCP server version

Replace @korely/mcp-server with @korely/mcp-server@x.y.z in the args array. Useful when you want reproducible behavior across machines.

Verbose logging

Set KORELY_LOG_LEVEL=debug in the env block to get detailed server logs in the Claude Code MCP log file. Helpful when you're debugging a vault that returns unexpected results.