# Connect Uni3K (大千) to an AI agent — setup guide for the agent

You are an AI agent. The user wants you to use Uni3K, their browser card library, as long-term memory through MCP.
Do the steps below for them. Ask the user only when a step says so. Do not show the token to anyone else or write it into shared files.

The user's message gave you:
- `TOKEN`: starts with `u3k_`. It identifies you to Uni3K.
- `EXTENSION_ID` (optional): 32 letters a–p. Pass it to the installer if given.

## 1. Check Node.js

Run `node --version`. You need 18 or later.
If Node.js is missing or older, ask the user to install the LTS version from https://nodejs.org/ and then continue.

## 2. Download the helper

macOS / Linux:

```sh
mkdir -p "$HOME/.uni3k/mcp" && curl -fsSL https://uni3k.com/uni3k-mcp.mjs -o "$HOME/.uni3k/mcp/uni3k-mcp.mjs"
```

Windows (PowerShell):

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.uni3k\mcp" | Out-Null
Invoke-WebRequest https://uni3k.com/uni3k-mcp.mjs -OutFile "$env:USERPROFILE\.uni3k\mcp\uni3k-mcp.mjs"
```

It is one JavaScript file with no dependencies. You may read it before running it.

## 3. Register the browser bridge

```sh
node "$HOME/.uni3k/mcp/uni3k-mcp.mjs" install --extension-id=EXTENSION_ID
```

(Windows: `node "$env:USERPROFILE\.uni3k\mcp\uni3k-mcp.mjs" install --extension-id=EXTENSION_ID`.)
Leave out `--extension-id=…` if you were not given one. It registers the helper for Chrome, Edge, Chromium and Brave. It changes nothing else on the computer.

## 4. Add Uni3K as an MCP server to yourself

Use the way your own client adds MCP servers. The server is a stdio command, with the token in the environment variable `UNI3K_TOKEN`.

- **Claude Code:**
  `claude mcp add uni3k --scope user --env UNI3K_TOKEN=TOKEN -- node "$HOME/.uni3k/mcp/uni3k-mcp.mjs"`
- **Claude Desktop:** add this under `mcpServers` in `claude_desktop_config.json`
  (macOS `~/Library/Application Support/Claude/`, Windows `%APPDATA%\Claude\`), keep the other entries, then ask the user to restart Claude Desktop:

  ```json
  "uni3k": { "command": "node", "args": ["/ABSOLUTE/PATH/TO/.uni3k/mcp/uni3k-mcp.mjs"], "env": { "UNI3K_TOKEN": "TOKEN" } }
  ```
  Use the absolute path of the user's home folder; `~` and `$HOME` are not expanded there. If `node` is not found by the app, use the full path from `which node` (Windows: `where node`).
- **Other clients:** the same command, arguments and environment variable.

## 5. Check it works

Call the `list_folders` tool.
- It answers: done. Tell the user in one sentence that Uni3K is connected.
- "Uni3K is not reachable": ask the user to keep Chrome or Edge open, and in Uni3K Settings > AI connections to turn on Local MCP and click "Allow" in the browser prompt. Then try again.
- "does not know this token": ask the user for a new token (Uni3K Settings > AI connections > New token).

## How to use it afterwards

- Search with `search_cards` before answering questions about things the user saved or may know.
- Save what is worth remembering with `save_card` (Markdown, a `# Title` line first). Keep each card short, one idea per card; card length is limited, so if a save is refused as too long, split it into several cards. Your cards go into your own space.
- You can change or delete only your own cards. Locked cards are never readable; you see only that one exists.
- The user's library is visible to you only if they allowed it for you in Settings.

---

For people: this page is written for AI agents. The guide for you is at https://uni3k.com/mcp (中文 https://uni3k.com/zh/mcp, 日本語 https://uni3k.com/ja/mcp).