flair-mcp

@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