> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/mcp/client-claude-desktop.md).

# Claude Desktop

Add the Telys MCP server to Claude Desktop on macOS or Windows so Claude gains an on-device memory it can search and add to.

Claude Desktop reads its MCP servers from one JSON file. Add a `telys` entry and Claude gains the 19 Telys memory tools in any conversation. Let `telys mcp install` write the entry, or edit the file yourself — both land in the same place.

## Configuration file

Claude Desktop's config lives at a fixed per-user path:

| OS      | Path                                                              |
| ------- | ----------------------------------------------------------------- |
| macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json`                     |

The file may not exist until you open Claude Desktop's settings once. Create it if missing; keep any `mcpServers` you already have and merge the `telys` key alongside them.

## Add the server

{% tabs %}
{% tab title="Automatic" icon="wand-magic-sparkles" %}
Let the installer write the entry:

```bash
telys mcp install --client claude-desktop
```

Then restart Claude Desktop. Confirm it landed with:

```bash
telys mcp status
```

{% endtab %}

{% tab title="Manual" icon="pen" %}
Open the config file and add the `telys` server block. Set `TELYS_MEMORY_PATH` only for a store other than `~/.telys/memory`.

{% code title="claude\_desktop\_config.json" lineNumbers="true" %}

```json
{
  "mcpServers": {
    "telys": {
      "command": "telys",
      "args": ["mcp"],
      "env": {
        "TELYS_MEMORY_PATH": "/Users/you/.telys/memory"
      }
    }
  }
}
```

{% endcode %}

Save the file and restart Claude Desktop.
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Claude Desktop is a GUI app and usually does **not** inherit your shell's `PATH`, so a bare `"command": "telys"` can fail with "server not found." Point `command` at the absolute path from `which telys` instead:

{% code title="claude\_desktop\_config.json" %}

```json
{
  "mcpServers": {
    "telys": {
      "command": "/Users/you/.local/bin/telys",
      "args": ["mcp"]
    }
  }
}
```

{% endcode %}

Run `which telys` in your terminal for the exact path (a pipx install is typically `~/.local/bin/telys`).
{% endhint %}

## Restart to load the server

Claude Desktop reads the config only at launch. Quit it completely — on macOS use Cmd-Q, not just closing the window — and reopen it so it spawns `telys mcp`.

## What you will see

After the restart, open the tools menu (the plug icon) in the message composer. A `telys` server appears with 19 tools — search and query, CRUD, collection admin, maintenance, and a repo auto-indexer (full list in the [MCP overview](https://docs.telys.ai/mcp/overview.md#the-tools-at-a-glance)). To confirm end to end, ask Claude in plain language:

```
Use telys to list my memory collections, then remember that my deploy runbook lives in ops/RUNBOOK.md.
```

Claude calls `telys_list_collections`, then `telys_add` (auto-creating a collection if needed), and reports what it stored. Telys is fully on-device after the one-time free `telys login` (device authorization) — no API key in the config, nothing leaves the machine.

{% hint style="info" %}
If the server does not appear, the runtime is usually the cause. Confirm `telys runtime verify` succeeds and the `command` path is correct. See [MCP client won't connect](https://docs.telys.ai/troubleshooting/mcp-client.md).
{% endhint %}

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Cursor &#x26; VS Code</strong></td><td>Add the same server to your editor.</td><td><a href="https://docs.telys.ai/mcp/client-cursor-vscode.md">Cursor &amp; VS Code</a></td></tr><tr><td><strong>Tool: telys_add</strong></td><td>How the model stores documents.</td><td><a href="https://docs.telys.ai/mcp/tool-add.md">telys_add</a></td></tr><tr><td><strong>Configuration &#x26; scoping</strong></td><td>Choose where memory lives per project.</td><td><a href="https://docs.telys.ai/mcp/configuration-and-scoping.md">Config &amp; scoping</a></td></tr></tbody></table>
