LifeOS MCP Server

MCP (Model Context Protocol) server for LifeOS Project Management and Life Design. This allows AI assistants like Claude to interact with your LifeOS projects, tasks, cycles, notes, contacts, and PPV life design system.

Installation

npm install -g @starascendin/lifeos-mcp

Or use directly with npx (no install needed):

npx @starascendin/lifeos-mcp --url <your-convex-url> --user-id <your-user-id> --api-key <your-api-key>

Configuration

Required Parameters

| Parameter | CLI Flag | Env Variable | Description | |-----------|----------|--------------|-------------| | Convex URL | --url, -u | CONVEX_URL | Your Convex deployment URL (e.g., https://your-app.convex.site) | | User ID | --user-id, -i | LIFEOS_USER_ID | Your LifeOS user ID | | API Key | --api-key, -k | LIFEOS_API_KEY | Your API key for authentication |

Optional FalkorDB Sidecar Parameters

These are required only for the Falkor graph tools.

| Env Variable | Description | |--------------|-------------| | FALKOR_BROWSER_ENDPOINT | FalkorDB Browser HTTP endpoint, defaults to https://falkordb.apps.rjlabs.dev | | FALKOR_GRAPH | Falkor graph name, defaults to lifeos_ppv | | FALKOR_PASS | Falkor password, used to mint short-lived browser tokens | | FALKOR_TOKEN / FALKOR_PAT | Optional pre-provisioned Falkor browser token | | FALKOR_USER | Falkor username, defaults to default | | FALKOR_HOST | Browser backend Redis host, defaults to localhost | | FALKOR_PORT | Browser backend Redis port, defaults to 6379 | | FALKOR_TLS | Browser backend Redis TLS flag, defaults to false |

Getting Your Credentials

1. Convex URL: Find in your Convex dashboard - use the .convex.site URL (not .convex.cloud)
2. User ID: In LifeOS app, go to Settings > Developer, or query from Convex Dashboard
3. API Key: Generate from your LifeOS settings or Convex dashboard

Usage with Claude Code

Add to your .mcp.json (project root or ~/.claude/mcp.json):

Using CLI flags:

{
  "mcpServers": {
    "lifeos": {
      "command": "npx",
      "args": [
        "@starascendin/lifeos-mcp",
        "--url", "https://your-app.convex.site",
        "--user-id", "your-user-id",
        "--api-key", "your-api-key"
      ]
    }
  }
}

Using environment variables:

{
  "mcpServers": {
    "lifeos": {
      "command": "npx",
      "args": ["@starascendin/lifeos-mcp"],
      "env": {
        "CONVEX_URL": "https://your-app.convex.site",
        "LIFEOS_USER_ID": "your-user-id",
        "LIFEOS_API_KEY": "your-api-key"
      }
    }
  }
}

Available Tools

Council

• run_council - Run the shared LifeOS council engine used by AI Panel and ZeroClaw skills

Project Management

• get_projects - List all projects with stats
• get_tasks - Get tasks with filters (project, status, priority)
• get_todays_tasks - Get today's tasks and top priorities
• get_overdue_tasks - Get open tasks that are already overdue
• create_issue - Create a new task/issue, optionally with an initial issue calendar block
• update_issue - Update an existing task, including estimate/story points and due date
• mark_issue_complete - Mark a task as done
• create_calendar_block - Create protected calendar-only time without creating a PM issue or Google event

Phases

• get_phases - Get all phases for a project
• get_phase - Get phase details with issues
• create_phase - Create a new phase
• update_phase - Update phase details
• delete_phase - Delete a phase
• assign_issue_to_phase - Assign/unassign issue to phase

Cycles/Sprints

• get_current_cycle - Get active cycle with progress
• assign_issue_to_cycle - Add task to a cycle

Agenda

• get_daily_agenda - Today's tasks, events, protected blocks, priorities
• get_weekly_agenda - Week's tasks, events, and protected blocks
• get_planning_context - Full day/week/current-cycle planning context for agents
• apply_planning_patch - Mutating planning patch for due dates, priorities, protected calendar-only blocks, current cycle, and notes

Habits

• get_habits - List active habits with streaks and completion stats
• get_habits_for_date - Get scheduled habits and their state for one day
• get_habit - Get one habit with extended stats
• create_habit - Create a new habit
• update_habit - Update a habit's details or active state
• archive_habit - Archive a habit while preserving history
• check_in_habit - Mark a habit complete, incomplete, or skipped for a date
• get_habit_check_ins - Get one habit's check-in history
• get_habit_categories - List habit categories
• create_habit_category - Create a habit category

Notes

• search_notes - Search voice memos/notes
• get_recent_notes - Get recent notes
• create_quick_note - Create a text note
• add_tags_to_note - Tag a note

People/Contacts

• get_people - List all contacts
• get_person - Get person details with AI profile
• search_people - Search contacts by name
• create_person - Create a new contact
• update_person - Update contact details
• get_memos_for_person - Get voice memos linked to a person
• get_person_timeline - Get interaction timeline
• link_memo_to_person - Link a memo to a person

Clients

• get_clients - List all clients
• get_client - Get client details
• get_projects_for_client - Get client's projects
• get_client_notes - List client/project/phase notes
• get_client_note - Get one client note with linked context
• create_client_note - Save requirement or account notes
• update_client_note - Update client notes
• create_client - Create a new client
• update_client - Update client details

Meetings

• get_fathom_meetings - List synced Fathom meetings
• get_fathom_meeting - Get Fathom meeting details
• get_fathom_transcript - Get full Fathom transcript
• search_fathom_meetings - Search Fathom meetings
• get_granola_meetings - List synced Granola meetings
• get_granola_meeting - Get Granola meeting details
• get_granola_transcript - Get full Granola transcript

CRM / Customer Success

• get_business_contacts - List business-marked Beeper threads with linked contact/client info
• get_client_success_workspace - Load one client's chats, meetings, notes, projects, and open work in one call

PPV Life Design

• get_ppv_workspace - Get vision, identity, pillars, linked projects, and available existing LifeOS projects
• get_active_vision_graph - Best default graph read for PPV/alignment questions; connects the active vision to projects, issues, and recent memos
• seed_ppv_beijing_workspace - Seed the Beijing Creative Salon example if no PPV vision exists
• upsert_ppv_vision - Create or update a PPV vision
• upsert_ppv_identity - Create or update identity components for a vision
• create_ppv_pillar / update_ppv_pillar / delete_ppv_pillar - Manage pillars and links to existing LifeOS projects

Unified Graph

• get_unified_life_graph - Build the user's full live unified graph across LifeOS domains
• get_project_graph - Read the graph neighborhood around one project
• get_initiative_graph - Read the graph neighborhood around one initiative
• get_person_graph - Read the graph neighborhood around one person/contact
• get_voice_memo_graph - Read the graph neighborhood around one voice memo
• get_cached_unified_graph - Read the materialized cached graph projection
• refresh_unified_graph_cache - Recompute inferred graph links and refresh the cached projection
• upsert_unified_graph_link / delete_unified_graph_link - Create or remove manual links between graph nodes

FalkorDB Sidecar Graph

• falkor_graph_schema - Inspect the Falkor graph contract, configured graph, allowed labels, relationship types, fields, query recipes, and agent link flow
• falkor_graph_query - Run guarded read-only Cypher against the Falkor PPV sidecar
• falkor_graph_link - Create/update an agent-owned AGENT_LINK relationship without mutating Convex-synced nodes or inferred PPV relationships
• falkor_graph_unlink - Remove a relationship previously created by falkor_graph_link

Falkor graph rules:

• Convex remains canonical for entity data.
• FalkorDB is a graph query/read sidecar for the PPV experiment.
• convexId is the stable id shared between Convex and Falkor nodes.
• Agents should call falkor_graph_schema first and prefer its query recipes.
• Agents may query graph data and write only agent-owned AGENT_LINK relationships.
• Every agent-created link must include a reason and confidence.
• Raw read queries should include LIMIT.

Shared Council Architecture

run_council calls the Convex POST /council-skill endpoint. That is the same shared council core used by:

• AI Panel council mode on Convex-backed models
• ZeroClaw's council skill
• MCP runtimes through run_council

This keeps council orchestration in one place instead of duplicating it per runtime.

CLI Help

lifeos-mcp --help
lifeos-mcp agenda day --date 2026-05-13
lifeos-mcp agenda week --week-start-date 2026-05-11
lifeos-mcp patch ./planning-patch.json --dry-run
lifeos-mcp ppv workspace
lifeos-mcp ppv graph
lifeos-mcp ppv seed
lifeos-mcp ppv vision --file ./ppv-vision.json

PPV CLI actions: workspace, graph, vision-graph, seed, vision, identity, pillar, update-pillar, delete-pillar.

For the broader graph family (get_project_graph, get_initiative_graph, get_person_graph, get_voice_memo_graph, get_unified_life_graph, cache refresh, and manual link tools), invoke the MCP tools directly from an agent runtime or use the lifeos CLI wrapper.

License

MIT