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