beacon-mcp

MCP server for Beacon — a personal, agent-readable knowledge system built on Supabase + pgvector.

What is Beacon?

Beacon is a private knowledge base that lives in Supabase. Every thought, decision, insight, meeting note, and project update you capture gets embedded with OpenAI and classified by Claude Haiku — making it semantically searchable by any AI agent that connects to this MCP server.

Tools

| Tool | Description | |------|-------------| | capture_thought | Save a thought, insight, decision, or note to Beacon | | semantic_search | Vector similarity search across all thoughts | | cross_domain_search | Semantic search with domain-table joins for richer context | | list_recent | Browse recent thoughts, filtered by domain/type/date | | brain_stats | Aggregate stats: thought counts by domain, type, week, top topics | | query_work_projects | List, get, or upsert work projects | | query_personal_projects | List, get, or upsert personal projects | | query_project_detail | Read/write child tables (fusion_intel_log, pidgeon_design_log) | | query_household | Manage household entries (maintenance, medical, vehicles, etc.) | | query_job_search | Track job pipeline: stages, follow-ups, interviews | | query_relationships | Manage professional relationships and warmth tracking | | log_decision | Write structured decisions to the decisions table | | weekly_review | Generate and store a weekly synthesis of Beacon activity |

Prerequisites

• A Supabase project with the Beacon schema applied (see BEACON_SPEC.md for SQL migrations)
• The process-thought Edge Function deployed to your Supabase project
• An OpenAI API key (for embedding generation)

Installation

Via npx (recommended)

Add to your MCP client config (e.g. Windsurf mcp_config.json, Claude Desktop claude_desktop_config.json):

{
  "beacon": {
    "args": ["-y", "@connorbritain/beacon-mcp@latest"],
    "command": "npx",
    "env": {
      "SUPABASE_URL": "https://your-project.supabase.co",
      "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key",
      "OPENAI_API_KEY": "your-openai-key"
    }
  }
}

Via global install

npm install -g @connorbritain/beacon-mcp@latest

Then point your MCP config to the globally installed binary:

{
  "beacon": {
    "args": ["beacon-mcp"],
    "command": "npx",
    "env": { ... }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | SUPABASE_URL | ✅ | Your Supabase project URL | | SUPABASE_SERVICE_ROLE_KEY | ✅ | Service role key (secret key) | | OPENAI_API_KEY | ✅ | Used for generating embeddings on search queries |

Development

git clone https://github.com/ConnorBritain/beacon-mcp.git
cd beacon-mcp
npm install
cp .env.example .env   # fill in your keys
npm run build
node dist/index.js

License

MIT