LifeOS MCP

Give any AI agent read access to your LifeOS knowledge base — Claude Desktop, Claude Code, Cursor, ChatGPT, Codex, or any MCP-compatible client.

The server reads from ~/lifeos/ and surfaces everything through lifeos:// resource URIs and lifeos__* tool names.

Install

Once published (coming soon)

npx lifeos-mcp

From source (now)

git clone https://github.com/bwats/lifeos-mcp
cd lifeos-mcp
npm install && npm run build
node bin/lifeos-mcp.js

Global install from source

cd ~/lifeos-mcp
npm install -g .
lifeos-mcp  # starts the MCP server on stdio

What it exposes

lifeos-mcp gives any MCP-compatible AI client direct read access to:

Surface	Path in ~/lifeos/	Tool
Identity	`identity.md`	`lifeos__get_identity`
Preferences	`preferences.md`	`lifeos__get_preferences`
Skills	`skills/*/`	`lifeos__list_skills`, `lifeos__read_skill`
Projects	`projects/*.md`	`lifeos__list_projects`, `lifeos__read_project`
Wiki	`wiki/pages/*/.md`	`lifeos__list_wiki_pages`, `lifeos__read_wiki_page`
Rules	`system/*.md`	`lifeos__list_rules`, `lifeos__read_rule`
Any file	(path-safe)	`lifeos__read_file`
Search	(full-text)	`lifeos__search`

Modes

Invocation	What happens
`lifeos-mcp`	Start MCP server on stdio (default)
`lifeos-mcp --stdio`	Start MCP server on stdio (explicit)
`lifeos-mcp list`	List rituals in `~/lifeos/cadence/rituals/`
`lifeos-mcp validate <ritual.md>`	Validate a ritual spec file
`lifeos-mcp render <ritual.md> --to <harness>`	Render ritual to a target harness
`lifeos-mcp --help`	Show all subcommands and options

Configure MCP clients

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "lifeos": {
      "command": "npx",
      "args": ["lifeos-mcp"]
    }
  }
}

Or from source:

{
  "mcpServers": {
    "lifeos": {
      "command": "node",
      "args": ["/Users/yourname/lifeos-mcp/bin/lifeos-mcp.js"]
    }
  }
}

Cursor (`settings.json`)

{
  "mcpServers": {
    "lifeos": {
      "command": "node",
      "args": ["/Users/yourname/lifeos-mcp/bin/lifeos-mcp.js"]
    }
  }
}

Claude Code (`~/.claude/settings.json`)

{
  "mcpServers": {
    "lifeos": {
      "command": "node",
      "args": ["/Users/yourname/lifeos-mcp/bin/lifeos-mcp.js"]
    }
  }
}

OpenAI Codex (`codex.json`)

{
  "mcpServers": {
    "lifeos": {
      "command": "node",
      "args": ["/Users/yourname/lifeos-mcp/bin/lifeos-mcp.js"]
    }
  }
}

Custom LifeOS path

Pass --lifeos-path or set LIFEOS_PATH env var:

{
  "mcpServers": {
    "lifeos": {
      "command": "node",
      "args": [
        "/Users/yourname/lifeos-mcp/bin/lifeos-mcp.js",
        "--lifeos-path", "/custom/path/to/lifeos"
      ]
    }
  }
}

Environment variables

Variable	Default	Description
`LIFEOS_PATH`	`~/lifeos`	Absolute path to the LifeOS root directory

Tools

Tool	Description
`lifeos__health`	Check server health and LifeOS availability
`lifeos__get_identity`	Read `identity.md` — frontmatter + body
`lifeos__get_preferences`	Read `preferences.md` — frontmatter + body
`lifeos__list_skills`	List all skill directory names in `~/lifeos/skills/`
`lifeos__read_skill`	Read documentation for a named skill
`lifeos__list_rules`	List rule/guideline names from `~/lifeos/system/`
`lifeos__read_rule`	Read a specific rule file
`lifeos__list_projects`	List project filenames from `~/lifeos/projects/`
`lifeos__read_project`	Read a specific project definition
`lifeos__list_wiki_pages`	List all wiki page paths recursively
`lifeos__read_wiki_page`	Read a wiki page by path
`lifeos__search`	Full-text search across all LifeOS files
`lifeos__read_file`	Read any file under `~/lifeos/` by relative path (path-traversal safe)
`lifeos__propose_edge`	Propose a typed semantic edge between two knowledge nodes
`lifeos__accept_edge`	Accept a proposed edge (write-opt-in required)
`lifeos__reject_edge`	Reject a proposed edge (write-opt-in required)
`lifeos__read_pending_queue`	List pending edge proposals (always read-only)

Resources

URI	Description
`lifeos://identity`	LifeOS identity profile (`identity.md`)
`lifeos://preferences`	User preferences (`preferences.md`)
`lifeos://skills/{name}`	Skill documentation for `~/lifeos/skills/{name}/`
`lifeos://projects/{name}`	Project definition for `~/lifeos/projects/{name}.md`
`lifeos://wiki/{+path}`	Wiki page at `~/lifeos/wiki/pages/{path}.md`
`lifeos://rules/{name}`	System rule at `~/lifeos/system/{name}.md`

All template resources support listing — clients can enumerate available resources.

CLI subcommands

# List all rituals with id, title, and trigger summary
lifeos-mcp list

# Validate a ritual spec (structural check)
lifeos-mcp validate ~/lifeos/cadence/rituals/morning-review.md

# Render a ritual to a harness
lifeos-mcp render ~/lifeos/cadence/rituals/morning-review.md --to openclaw
lifeos-mcp render ~/lifeos/cadence/rituals/morning-review.md --to claude-code

Renderer interface (pluggable)

Third-party renderers plug in at runtime via registerRenderer:

import { registerRenderer } from "lifeos-mcp/dist/renderers/index.js";

registerRenderer({
  name: "my-harness",
  async render(spec, body, ctx) {
    return {
      files: [{ path: "/out/job.json", content: JSON.stringify(spec) }],
      summary: `Rendered ${spec.id} to my-harness`,
    };
  },
});

Built-in renderers: openclaw (cron job JSON), claude-code (slash command + launchd plist).

Security

All file paths are validated to stay within the LifeOS root — no path traversal possible.
The server is read-only by default; write tools (lifeos__propose_edge, lifeos__accept_edge, lifeos__reject_edge) require explicit opt-in via ~/Library/Application Support/LifeOS/mcp-write-config.json.
Only files under ~/lifeos/ (or LIFEOS_PATH) are accessible.

Build

cd ~/lifeos-mcp
npm install
npm run build
# Output: dist/ + bin/lifeos-mcp.js

License

MIT

lifeos-mcp