# Setting Up Feather DB MCP in Claude Desktop: Step-by-Step

> Give Claude Desktop a persistent memory backend in 10 minutes. Install feather-db, start feather-serve, wire up the MCP config — and Claude will remember everything you tell it across conversations.

- **Category**: Tutorial
- **Read time**: 6 min read
- **Date**: June 16, 2026
- **Author**: Feather DB (Engineering)
- **URL**: https://getfeather.store/theory/feather-db-mcp-claude-desktop-setup

---

## What you'll build

By the end of this guide, Claude Desktop will have access to 14 MCP tools backed by a Feather DB instance running on your machine. You'll be able to say "Remember that I'm working on a FastAPI project" and Claude will recall it in future conversations — with adaptive decay so stale memories don't crowd out current ones.

## Step 1: Install Feather DB

```bash
# Python 3.9+ required
pip install feather-db

# Verify installation
feather-serve --version
# feather-serve 0.15.1

```

Feather DB is a pure Python package with a C++17 core bundled as a pre-compiled wheel. No system dependencies, no Rust toolchain, no Docker required for basic setup. The wheel supports macOS (Apple Silicon + Intel), Linux (x86_64), and Windows (x86_64).

## Step 2: Create your memory file

```bash
# Create a directory for your Feather data
mkdir -p ~/feather-memory

# Initialize a memory file (768-dim for text-embedding-3-small / voyage-3)
feather-init ~/feather-memory/claude_memory.feather --dim 768

# Verify
ls -la ~/feather-memory/
# -rw-r--r-- 1 user staff 2.4K claude_memory.feather

```

## Step 3: Start feather-serve with a real embedder

feather-serve needs an embedding provider to encode text into vectors. Pick the provider you already have an API key for:

```bash
# Google Gemini embeddings (text-embedding-004)
export GOOGLE_API_KEY=your_key_here
feather-serve ~/feather-memory/claude_memory.feather \
  --embed-provider gemini \
  --port 7700

# OR: OpenAI text-embedding-3-small
export OPENAI_API_KEY=your_key_here
feather-serve ~/feather-memory/claude_memory.feather \
  --embed-provider openai \
  --port 7700

# OR: Voyage AI voyage-3 (recommended for best recall)
export VOYAGE_API_KEY=your_key_here
feather-serve ~/feather-memory/claude_memory.feather \
  --embed-provider voyage \
  --port 7700

# OR: Local Ollama (no API key needed)
feather-serve ~/feather-memory/claude_memory.feather \
  --embed-provider ollama \
  --embed-model nomic-embed-text \
  --port 7700

```

The server will print: `Feather DB serving at http://localhost:7700 | MCP at http://localhost:7700/mcp`. Keep this terminal open — or set it up as a system service (see troubleshooting section).

## Step 4: Locate and edit claude_desktop_config.json

Claude Desktop reads MCP server configuration from a JSON file. The file path depends on your OS:

OSConfig file path

macOS`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows`%APPDATA%\Claude\claude_desktop_config.json`
Linux`~/.config/Claude/claude_desktop_config.json`

Open the file in any text editor (create it if it doesn't exist yet):

```json
{
  "mcpServers": {
    "feather-memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-http-sse"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:7700/mcp"
      }
    }
  }
}

```

If you already have other MCP servers configured, add `feather-memory` as an additional key inside `mcpServers`.

## Step 5: Verify the MCP connection

Restart Claude Desktop (quit and reopen — not just a window refresh). After restarting, open any conversation and look for the tools icon (hammer symbol) in the message input area. Click it — you should see 14 Feather DB tools listed:

- `feather_add` — store a new memory

- `feather_search` — semantic search

- `feather_context_chain` — graph-traversal retrieval

- `feather_hybrid_search` — BM25 + dense search

- `feather_add_edge` — link memories

- `feather_update_recall` — boost stickiness

- `feather_delete` — remove a memory

- `feather_get` — retrieve by ID

- `feather_list` — list recent memories

- ... and 5 more namespace/entity management tools

## Step 6: Add your first memory via Claude

In a new Claude Desktop conversation, type:

Please remember that I'm working on a FastAPI backend for a fintech startup, we're using PostgreSQL, and I prefer detailed code examples over high-level explanations.

Claude will call `feather_add` (you'll see the tool call in the conversation) and confirm the memory was saved. It will also set appropriate importance and entity tags.

## Step 7: Verify recall works

Start a completely new conversation (close and reopen Claude Desktop). Ask:

What do you know about what I'm working on?

Claude will call `feather_search` or `feather_context_chain`, retrieve the stored memory, and respond with the context you saved. This works across sessions because the `.feather` file persists on disk.

## Troubleshooting

**Port conflict:** If port 7700 is in use, start feather-serve on a different port (`--port 7701`) and update the `MCP_SERVER_URL` in your config accordingly.

**API key missing:** If the embedding provider can't be reached, feather-serve will log the error to the terminal. Verify your environment variable is exported correctly in the same shell session where you run feather-serve. On macOS, environment variables set in `.zshrc` require a new terminal session to take effect.

**Version mismatch:** Claude Desktop's MCP support requires Claude Desktop 0.10.0 or later. Check your Claude Desktop version in the About menu.

**Run feather-serve as a persistent service (macOS):**

```bash
# Create a launchd plist for automatic startup
cat > ~/Library/LaunchAgents/com.feather.serve.plist 

  Labelcom.feather.serve
  ProgramArguments
  
    /usr/local/bin/feather-serve
    /Users/YOUR_USER/feather-memory/claude_memory.feather
    --embed-providergemini
    --port7700
  
  EnvironmentVariables
  
    GOOGLE_API_KEYyour_key_here
  
  RunAtLoad
  KeepAlive

EOF

launchctl load ~/Library/LaunchAgents/com.feather.serve.plist

```

After the launchd setup, feather-serve starts automatically at login and restarts if it crashes — no more manual terminal sessions needed.

**Admin SPA:** While feather-serve is running, you can also browse to `http://localhost:7700/admin/` to view stored memories, run manual searches, and inspect the graph via the Atlas admin UI.

**Install:** `pip install feather-db` · **GitHub:** [github.com/feather-store/feather](https://github.com/feather-store/feather)

---

*This is the machine-readable mirror of the theory post at [getfeather.store/theory/feather-db-mcp-claude-desktop-setup](https://getfeather.store/theory/feather-db-mcp-claude-desktop-setup). For the full Feather DB documentation, see [getfeather.store/llms-full.txt](https://getfeather.store/llms-full.txt).*