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

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

# 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

# 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:

# 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:

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

{
  "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):

# Create a launchd plist for automatic startup
cat > ~/Library/LaunchAgents/com.feather.serve.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.feather.serve</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/feather-serve</string>
    <string>/Users/YOUR_USER/feather-memory/claude_memory.feather</string>
    <string>--embed-provider</string><string>gemini</string>
    <string>--port</string><string>7700</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>GOOGLE_API_KEY</key><string>your_key_here</string>
  </dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
</dict>
</plist>
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