LifeOS MCP server

Name: LifeOS MCP server
Author: Edris Ranjbar

Read and update a self-hosted Edi Life OS dashboard: goals, tasks, habits, expenses and notes

Official · Edris Ranjbar JavaScript Local · stdio Productivity Finance and payments

GitHub npm Website

34 popularity score ★ 115 ↓ 43/wk

Connect your client

Local (npm)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

It needs LIFEOS_BASE_URL, LIFEOS_API_TOKEN. Replace each <NAME> with your value.

Claude CodeTerminal

claude mcp add lifeos -e LIFEOS_BASE_URL=<LIFEOS_BASE_URL> -e LIFEOS_API_TOKEN=<LIFEOS_API_TOKEN> -- npx -y @edicodes/lifeos-mcp

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "lifeos": {
      "command": "npx",
      "args": [
        "-y",
        "@edicodes/lifeos-mcp"
      ],
      "env": {
        "LIFEOS_BASE_URL": "<LIFEOS_BASE_URL>",
        "LIFEOS_API_TOKEN": "<LIFEOS_API_TOKEN>"
      }
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "lifeos": {
      "command": "npx",
      "args": [
        "-y",
        "@edicodes/lifeos-mcp"
      ],
      "env": {
        "LIFEOS_BASE_URL": "<LIFEOS_BASE_URL>",
        "LIFEOS_API_TOKEN": "<LIFEOS_API_TOKEN>"
      }
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "lifeos": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@edicodes/lifeos-mcp"
      ],
      "env": {
        "LIFEOS_BASE_URL": "<LIFEOS_BASE_URL>",
        "LIFEOS_API_TOKEN": "<LIFEOS_API_TOKEN>"
      }
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.lifeos]
command = "npx"
args = ["-y", "@edicodes/lifeos-mcp"]

[mcp_servers.lifeos.env]
LIFEOS_BASE_URL = "<LIFEOS_BASE_URL>"
LIFEOS_API_TOKEN = "<LIFEOS_API_TOKEN>"

Gemini CLITerminal

gemini mcp add --scope user -e LIFEOS_BASE_URL=<LIFEOS_BASE_URL> -e LIFEOS_API_TOKEN=<LIFEOS_API_TOKEN> lifeos npx -- -y @edicodes/lifeos-mcp

Local (from source)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

It needs LIFEOS_BASE_URL, LIFEOS_API_TOKEN. Replace each <NAME> with your value.

FirstTerminal

git clone https://github.com/edrisranjbar/lifeos.git
cd lifeos/mcp
npm ci

Claude CodeTerminal

claude mcp add lifeos -e LIFEOS_BASE_URL=<LIFEOS_BASE_URL> -e LIFEOS_API_TOKEN=<LIFEOS_API_TOKEN> -- node '<ABSOLUTE_PATH_TO_CLONE>/mcp/src/index.js'

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "lifeos": {
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/mcp/src/index.js"
      ],
      "env": {
        "LIFEOS_BASE_URL": "<LIFEOS_BASE_URL>",
        "LIFEOS_API_TOKEN": "<LIFEOS_API_TOKEN>"
      }
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "lifeos": {
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/mcp/src/index.js"
      ],
      "env": {
        "LIFEOS_BASE_URL": "<LIFEOS_BASE_URL>",
        "LIFEOS_API_TOKEN": "<LIFEOS_API_TOKEN>"
      }
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "lifeos": {
      "type": "stdio",
      "command": "node",
      "args": [
        "<ABSOLUTE_PATH_TO_CLONE>/mcp/src/index.js"
      ],
      "env": {
        "LIFEOS_BASE_URL": "<LIFEOS_BASE_URL>",
        "LIFEOS_API_TOKEN": "<LIFEOS_API_TOKEN>"
      }
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.lifeos]
command = "node"
args = ["<ABSOLUTE_PATH_TO_CLONE>/mcp/src/index.js"]

[mcp_servers.lifeos.env]
LIFEOS_BASE_URL = "<LIFEOS_BASE_URL>"
LIFEOS_API_TOKEN = "<LIFEOS_API_TOKEN>"

Gemini CLITerminal

gemini mcp add --scope user -e LIFEOS_BASE_URL=<LIFEOS_BASE_URL> -e LIFEOS_API_TOKEN=<LIFEOS_API_TOKEN> lifeos node -- '<ABSOLUTE_PATH_TO_CLONE>/mcp/src/index.js'

Settings 3

`LIFEOS_BASE_URL`	Required: Base address of your LifeOS app, such as https://lifeos.example.com; HTTP only for localhost.
`LIFEOS_API_TOKEN`	Required: The same API token set in the app's config, at least 32 characters.
`LIFEOS_MCP_TIMEOUT_MS`	Optional: Request timeout in milliseconds, 100 to 120000, default 10000.

What it does

Edi Life OS is a self-hosted PHP and MySQL dashboard that keeps habits, SMART goals, Kanban tasks, a Pomodoro timer, a finance ledger and notes in one place. Its maker ships a small Node.js program alongside it, published on npm as @edicodes/lifeos-mcp, that gives an MCP client access to that dashboard. It does not open the database: every call goes to the app's own /api/v1 HTTP API with a bearer token.

Version 2.0.0 has 15 tools. All reading goes through one tool, lifeos_query, whose type argument picks the dashboard, goals, tasks, habits, today's habits, a finance summary, expenses, incomes or notes. The other 14 tools each make one change: create, edit or delete goals, tasks and notes, tick or untick a habit, log an expense or set income. Keeping writes as separate tools means a client asks for approval on each one, and the deletes are flagged as destructive. Version 2.0.0 replaced the twelve separate read tools of 1.x (lifeos_dashboard, lifeos_list_goals and the rest), so clients that call those names directly have to be updated.

The request timeout is 10 seconds by default; LIFEOS_MCP_TIMEOUT_MS accepts values from 100 to 120000 milliseconds, a range given in the program's --help text (mcp/src/index.js) but not in the README.

What it needs

Runtime	Node.js 22+

A running Edi Life OS install (PHP 8.1+ with pdo_mysql and mbstring, MySQL 8+ or MariaDB 10.4+, via Docker Compose, shared hosting or PHP's built-in server) with an api_token of at least 32 characters set in config.php or LIFEOS_API_TOKEN. Node.js 22.9 or later (24 recommended) for the MCP server. A remote LifeOS host must be served over verified HTTPS.

Limits

Runs over stdio only; there is no hosted MCP endpoint, and /api/v1 is not an MCP URL. The API token acts for one account (api_user_id, default 1) and has no scopes; the app has no per-user tokens or rate limiting. Finance amounts are in Toman and habit dates default to today in Asia/Tehran. Secret notes are left out unless include_secret is passed and the server allows it. Plain HTTP is accepted only for localhost; base URLs with credentials, query strings or subpaths are rejected. A timeout can occur after a write has been saved, so its docs advise checking state before retrying a create or expense call. Open browser tabs need a reload to show changes.

Who it suits

Suits someone who already runs Edi Life OS, or is willing to host it, and wants an assistant to log habits and expenses, plan goals and manage tasks in it. It is of no use without that app: it does not connect to other to-do, habit or budgeting services. Because the single token can write and delete across goals, tasks and notes for one account, pick a client that asks before each write. Those who want a hosted service or a different currency and time zone for finance and habits should look elsewhere.

Tools 15

lifeos_query: Read-only lookup of the dashboard, goals, tasks, habits, finances or notes, picked by type
lifeos_create_goal: Add a new goal
lifeos_update_goal: Change fields of an existing goal by id
lifeos_delete_goal: Permanently remove a goal
lifeos_create_task: Add a task to a board or goal
lifeos_update_task: Change fields of an existing task
lifeos_complete_task: Mark a task as done
lifeos_delete_task: Permanently remove a task
lifeos_complete_habit: Tick a habit for a date, today by default
lifeos_uncomplete_habit: Untick a habit for a date
lifeos_log_expense: Record an expense in the finance ledger
lifeos_set_income: Set the income for a period
lifeos_create_note: Create a note
lifeos_update_note: Edit an existing note
lifeos_delete_note: Permanently remove a note

Popularity

34 popularity score

★ 115 ↓ 43/wk

GitHub stars, whole repository	115	13.1 points
npm downloads, last week	43	13.1 points
Official server	Yes	8 points

It lives in the folder mcp of edrisranjbar/lifeos, which holds more than this server. Its stars are the whole repository's, so in the score they never count for more than its own downloads.

Measured 2026-11-07. How the score works.

Where it is published

Code	edrisranjbar/lifeos/mcp ★ 115, the whole repository
npm	@edicodes/lifeos-mcp 2.0.0, 2026-10-10

What it can reach

Runs	On your machine
Reaches	The internet
Changes things	Yes: it can write, send, create or delete
Sign-in	An API key or token
Licence	MIT (npm)
Last code change	2026-10-30

Runs on your machine over stdio and makes HTTP calls only to the LifeOS base URL you give it, using a bearer token; it exposes no SQL, file, config or credential tools and no tool returns the token. The token can read and write goals, tasks, habits, finances and notes for one account (api_user_id, default 1), with no scopes or rate limits in the app. Delete tools remove data permanently and are marked destructive; whether you are asked to approve them depends on your client. Secret notes are hidden unless explicitly requested and permitted; the secret flag is not encryption.

Over time

GitHub stars, whole repository 115 +47 (+69 %)

11568

14 Oct 20267 Nov 2026

npm downloads a week 43 −191 (−82 %)

23813

14 Oct 20267 Nov 2026

Popularity score 34 −12 (−25 %)

4626

14 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-14.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![LifeOS MCP server on EveryMCPServer](https://everymcpserver.com/badge/lifeos.svg)](https://everymcpserver.com/servers/lifeos)

Connect your client

Add in one click

Or add it by command or config

Add in one click

Or add it by command or config

Settings 3

What it does

What it needs

Limits

Who it suits

Tools 15

Similar servers

LunchMoney MCP Server

MCP Server Trello

Karakeep MCP Server

Odoo MCP

mealie-mcp-server

Mindwtr MCP Server