# Reflect MCP Server – Setup Guide

Reflect's macOS desktop app includes a built-in MCP server that lets MCP clients (Claude Code, Codex, Cursor, etc.) search and interact with your Reflect notes. This guide walks you through enabling it.

> **Note:** This is a beta release. You can search, read, create, and append to notes. Editing or deleting existing notes is not yet supported.

---

## Prerequisites

- **Reflect macOS desktop app** installed and running
- **Claude Code**, **Codex**, or **Cursor IDE** installed

---

## Step 1: Enable the MCP Server in Reflect

1. Open the **Reflect** macOS desktop app
2. Go to **Settings** and find the MCP server toggle
3. Enable the MCP server

Once enabled, Reflect exposes an MCP endpoint at `http://127.0.0.1:7676/mcp`.

---

## Step 2: Register the MCP Server with Your Client

### Claude Code (CLI & Desktop Code Tab)

Run this command in your terminal:

```bash
claude mcp add --scope user --transport http reflect-notes http://127.0.0.1:7676/mcp
```

### Codex (CLI & App)

```bash
codex mcp add reflect-notes --url http://127.0.0.1:7676/mcp
```

### Cursor IDE

Configure Cursor by editing the MCP config file directly:

1. Open (or create) `~/.cursor/mcp.json`
2. Add the following entry under `mcpServers`:
   ```json
   {
     "mcpServers": {
       "reflect-notes": {
         "url": "http://127.0.0.1:7676/mcp"
       }
     }
   }
   ```
3. If you already have other MCP servers, merge `reflect-notes` into the existing `mcpServers` object instead of replacing the whole file.

---

## Step 3: Restart & Verify

- **Restart** your current Claude Code, Codex, or Cursor session if there is any so it picks up the new MCP server
- Make sure the **Reflect desktop app is running** — the MCP server only works while Reflect is open
- Test by asking your client to search your Reflect notes

---

## What you can do

- Search notes by text, tag, date, or backlinks
- Retrieve any note or your daily note
- Create new notes and append to your daily note
- Browse and manage tags

---

## Troubleshooting

| Issue | Fix |
|---|---|
| MCP server not connecting | Ensure Reflect is open and the MCP server is enabled in settings |
| `claude` command not found | Use the full path: `"/Users/<you>/Library/Application Support/Claude/claude-code/<version>/claude"` |
| Changes not taking effect | Restart your Claude Code / Codex / Cursor session after adding the server |
| Chat tab not working | Verify `mcp-proxy` is installed and the path in the config is correct |

---

## Notes

- The server runs locally on `127.0.0.1:7676` — no data leaves your machine via this connection
- The MCP server is scoped to `user` level for Claude Code, so it works across all your projects
- ChatGPT Desktop is **not supported**
