lipi-mcp

MCP server for Lipi — Indic-first notes with romanized Devanagari search (mero → मेरो, namaste → नमस्ते) and Bikram Sambat dates. Connect Claude Desktop, Cursor, Codex, or any MCP host to your Lipi vault.

MCP is a thin stdio wrapper over the Lipi API — no data duplication, safe concurrent updates.

Install — npx / bunx (no global install needed)

# run directly (always latest)
npx -y lipi-mcp --help
bunx lipi-mcp --help

# or pin version
npx -y [email protected] --api https://lipi-api.bharosilo.com --token <jwt>

Quickstart

1. Get a token — sign up at https://lipi.bharosilo.com, then copy the JWT from your browser (DevTools → localStorage accessToken), or call POST https://lipi-api.bharosilo.com/v1/auth/login directly.

2. Run MCP:

# prod (default)
LIPI_ACCESS_TOKEN=<jwt> npx -y lipi-mcp
# or explicit
LIPI_API_URL=https://lipi-api.bharosilo.com LIPI_ACCESS_TOKEN=<jwt> npx -y lipi-mcp
# dev
LIPI_API_URL=http://localhost:8080 LIPI_ACCESS_TOKEN=<jwt> npx -y lipi-mcp
# or
bunx lipi-mcp --api https://lipi-api.bharosilo.com --token <jwt>

4. Configure your MCP host — claude_desktop_config.json (Claude Desktop) or ~/.cursor/mcp.json (Cursor):

{
  "mcpServers": {
    "lipi": {
      "command": "npx",
      "args": ["-y", "lipi-mcp", "--api", "https://lipi-api.bharosilo.com"],
      "env": {
        "LIPI_ACCESS_TOKEN": "<paste-jwt-here>",
        "LIPI_REFRESH_TOKEN": "<optional-refresh-token>"
      }
    }
  }
}

For local dev:

{
  "mcpServers": {
    "lipi": {
      "command": "npx",
      "args": ["-y", "lipi-mcp", "--api", "http://localhost:8080"],
      "env": {
        "LIPI_API_URL": "http://localhost:8080",
        "LIPI_ACCESS_TOKEN": "<paste-jwt-here>"
      }
    }
  }
}

With bunx:

{
  "mcpServers": {
    "lipi": {
      "command": "bunx",
      "args": ["lipi-mcp", "--api", "https://lipi-api.bharosilo.com"],
      "env": { "LIPI_ACCESS_TOKEN": "<jwt>" }
    }
  }
}

Restart the host. You should see 9 tools: lipi_login, lipi_list_notes, lipi_read_note, lipi_read_note_by_name, lipi_create_note, lipi_update_note, lipi_rename_note, lipi_delete_note, lipi_search.

Tools

| Tool | Maps to | Notes | |---|---|---| | lipi_login | POST /v1/auth/login | Caches token for session; also verifies via GET /v1/me | | lipi_list_notes | GET /v1/notes / ?tree=1 | Flat NoteMeta[] or NoteTree[] | | lipi_read_note | GET /v1/notes/:id | Full Note + ETag | | lipi_read_note_by_name | GET /v1/notes-by-name?name= | Wikilink resolver [[Name]] | | lipi_create_note | POST /v1/notes | Idempotent on (user_id, path) | | lipi_update_note | PUT /v1/notes/:id + If-Match | Requires ifMatch = updatedAt (RFC3339Nano); 409 on stale | | lipi_rename_note | PATCH /v1/notes/:id | 409 if path taken | | lipi_delete_note | DELETE /v1/notes/:id | 204 → {deleted:true} | | lipi_search | GET /v1/search?q= | Romanized: mero → मेरो (+2 exact / +1 prefix) |

Auth: Authorization: Bearer <jwt> + Cookie: lipi_refresh=<token> (auto refresh on 401 → retry once).

Env / Flags

| Flag / Env | Default | Description | |---|---|---| | --api / LIPI_API_URL | https://lipi-api.bharosilo.com | Lipi API base URL (http://localhost:8080 for dev) | | --token / LIPI_ACCESS_TOKEN | — | JWT (15m) | | --refresh / LIPI_REFRESH_TOKEN | — | Opaque refresh (30d), HttpOnly lipi_refresh at rest |

Dev

bun install
bun run build
node dist/index.js --help

# inspect with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

Publish

bun run build
npm publish --access public
# then users can npx -y lipi-mcp@latest