npm package: @starascendin/lifeos-mcp
Description: MCP server for LifeOS Project Management - manage projects, tasks, notes, and contacts via AI assistants
Author: Bryan Liu
Latest version: 0.7.58

# LifeOS MCP Server

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

## Installation

```bash
npm install -g @starascendin/lifeos-mcp
```

Or use directly with npx (no install needed):

```bash
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 |

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

```json
{
  "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:

```json
{
  "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
- **llm_council_deliberate** - Run the separate long-running LLM Council workflow
- **llm_council_list_conversations** - List saved LLM Council conversations
- **llm_council_get_deliberation** - Get a saved LLM Council deliberation

### 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
- **update_issue** - Update an existing task, including estimate/story points
- **mark_issue_complete** - Mark a task as done

### 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, priorities
- **get_weekly_agenda** - Week's tasks and events

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

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

```bash
lifeos-mcp --help
```

## License

MIT