> 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

Claude Desktop reads its MCP servers from one JSON file. Add a `telys` entry and Claude gains the five 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 five tools: `telys_search`, `telys_add`, `telys_create_collection`, `telys_list_collections`, and `telys_stats`. 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 — 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](/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="/pages/Xi6UuKyPqX5ZPtarQnMw">/pages/Xi6UuKyPqX5ZPtarQnMw</a></td></tr><tr><td><strong>Tool: telys_add</strong></td><td>How the model stores documents.</td><td><a href="/pages/7SvzDlAaeA3qddGl1gOl">/pages/7SvzDlAaeA3qddGl1gOl</a></td></tr><tr><td><strong>Configuration &#x26; scoping</strong></td><td>Choose where memory lives per project.</td><td><a href="/pages/WSNXqM7PJEas18L3bBPP">/pages/WSNXqM7PJEas18L3bBPP</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.telys.ai/mcp/client-claude-desktop.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.