@tpsdev-ai/flair-mcp

MCP server for Flair — persistent memory for Claude Code, Cursor, and any MCP client.

Quick Start

Claude Code

# Add to your project's .mcp.json
cat > .mcp.json << 'EOF'
{
  "mcpServers": {
    "flair": {
      "command": "npx",
      "args": ["-y", "@tpsdev-ai/flair-mcp"],
      "env": {
        "FLAIR_AGENT_ID": "my-project"
      }
    }
  }
}
EOF

npx -y @tpsdev-ai/flair-mcp fetches and runs the server on demand — no global install needed. (flair init wires this for you automatically; see below.)

Prerequisites

You need a running Flair instance. The one-command front door:

npm install -g @tpsdev-ai/flair
flair init --agent my-project   # installs Harper, creates the agent, wires MCP clients

Tools

Once configured, Claude Code (or any MCP client) gets these tools:

| Tool | Description | |------|-------------| | memory_search | Semantic search across memories. Understands "what happened today". | | memory_store | Save a memory with type (lesson/decision/fact) and durability. | | memory_get | Retrieve a specific memory by ID. | | memory_delete | Delete a memory. | | bootstrap | Cold-start context — soul + recent memories in one call. | | soul_set | Set personality or project context (included in every bootstrap). | | soul_get | Get a personality or project context entry. |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | FLAIR_AGENT_ID | (required) | Agent identity for memory scoping | | FLAIR_URL | http://localhost:19926 | Flair server URL | | FLAIR_KEY_PATH | auto-resolved | Path to Ed25519 private key | | FLAIR_ADMIN_USER | (optional) | Admin username for Basic auth (standalone mode) | | FLAIR_ADMIN_PASSWORD | (optional) | Admin password for Basic auth (standalone mode) |

How It Works

Claude Code ↔ stdio ↔ flair-mcp ↔ HTTP ↔ Flair (Harper)

The MCP server is a thin wrapper around @tpsdev-ai/flair-client. All memory is stored in your local Flair instance with Ed25519 authentication. Nothing leaves your machine unless you point FLAIR_URL at a remote server.

Remote Flair

Point to a remote Flair instance:

{
  "mcpServers": {
    "flair": {
      "command": "npx",
      "args": ["-y", "@tpsdev-ai/flair-mcp"],
      "env": {
        "FLAIR_AGENT_ID": "my-project",
        "FLAIR_URL": "http://your-server:19926"
      }
    }
  }
}

Copy your key from the server: scp server:~/.flair/keys/my-project.key ~/.flair/keys/

License

Apache 2.0