tidepools-mcp

MCP server for Tidepools notes, journals, and todos.

Tidepools is a daily journaling app with a proactive AI coach. Learn more or download the Mac or iOS apps at https://tidepools.ai.

This package runs a local stdio MCP server and forwards tool calls to the Tidepools API. It is useful for MCP hosts that do not yet support remote Streamable HTTP MCP with OAuth.

If your MCP host supports remote MCP servers, prefer the hosted Tidepools MCP endpoint instead:

https://tidepools.ai/mcp

Requirements

• Node.js 20 or newer
• A Tidepools account with an active subscription
• A Tidepools MCP API token

Create and revoke local MCP API tokens from the Tidepools app's MCP Config dialog. Tokens are shown only once, so copy the token when it is created.

Installation

Most MCP hosts can run the package with npx, so no global installation is required:

npx -y tidepools-mcp

You can also install it globally:

npm install -g tidepools-mcp
tidepools-mcp

MCP Host Configuration

Add a stdio MCP server entry similar to this:

{
  "mcpServers": {
    "tidepools": {
      "command": "npx",
      "args": ["-y", "tidepools-mcp"],
      "env": {
        "TIDEPOOLS_API_TOKEN": "<paste-token-here>",
        "TIDEPOOLS_API_BASE_URL": "https://tidepools.ai"
      }
    }
  }
}

TIDEPOOLS_API_BASE_URL is optional and defaults to https://tidepools.ai.

Environment Variables

| Variable | Required | Description | | --- | --- | --- | | TIDEPOOLS_API_TOKEN | Yes | Bearer token created from the Tidepools MCP Config dialog. | | TIDEPOOLS_API_BASE_URL | No | Tidepools API origin. Defaults to https://tidepools.ai. |

Tools

get_journal_entries

Retrieve journal entries by date range.

Input:

{
  "startDate": "2026-06-01",
  "endDate": "2026-06-07"
}

endDate is optional. Date ranges are limited to 120 days.

get_page

Retrieve a non-journal page by exact title.

Input:

{
  "title": "Roadmap"
}

search_notes

Search across Tidepools pages and journal entries.

Input:

{
  "query": "launch notes",
  "scope": "all",
  "limit": 10
}

scope can be all, pages, or journals. limit is capped at 50.

search_todos

Search todos by text and/or status.

Input:

{
  "text": "docs",
  "statuses": ["NOW", "TODO"],
  "limit": 25
}

Valid statuses are NOW, LATER, TODO, DOING, WAITING, and DONE. limit is capped at 100.

create_todo

Append a new todo to today's journal entry.

Input:

{
  "text": "write release notes",
  "status": "TODO"
}

The text should not include the leading - STATUS; pass the status separately. If omitted, status defaults to TODO.

edit_todo

Edit a todo returned by search_todos.

Input:

{
  "todoId": "<todo-id-from-search_todos>",
  "expectedRevisionNumber": 12,
  "text": "write final release notes",
  "status": "DOING"
}

todoId and expectedRevisionNumber make the edit stale-safe. Fetch the latest todo before retrying after a revision conflict.

append_to_today_journal

Append raw Tidepools markdown to today's journal entry.

Input:

{
  "text": "- NOW write docs"
}

edit_page

Apply revision-checked 1-based line edits to a non-journal page.

Input:

{
  "title": "Roadmap",
  "expectedRevisionNumber": 12,
  "edits": [
    {
      "startLine": 3,
      "endLine": 3,
      "replacementText": "- DONE ship MCP docs"
    }
  ]
}

Use either title or pageId. Read the page first and pass its latest revisionNumber as expectedRevisionNumber.

edit_journal_entry

Apply revision-checked 1-based line edits to a journal entry.

Input:

{
  "date": "2026-06-13",
  "expectedRevisionNumber": 8,
  "edits": [
    {
      "startLine": 5,
      "endLine": 5,
      "replacementText": "- DONE update journal"
    }
  ]
}

Tidepools Markdown Notes

Tidepools pages use a markdown-like format:

• Todos are bullet points whose text starts with one of these statuses: TODO, DOING, NOW, LATER, DONE, or WAITING.
• Formulas are bullet points whose text starts with =, such as - =ask("question"). Preserve formula lines unless explicitly editing them.
• Wiki links use [[Page Title]] syntax.
• Line edits use raw Tidepools markdown in replacementText. Do not include line-number prefixes.
• Prefer minimal line-based edits and preserve indentation, bullets, todo statuses, formulas, and links unless the requested change requires modifying them.

Local Development

From this package directory:

npm install
npm run build

To test against a local Tidepools server, build the package and point your MCP host at the compiled entrypoint:

{
  "mcpServers": {
    "tidepools": {
      "command": "node",
      "args": ["/absolute/path/to/lexicaltoy/packages/tidepools-mcp/build/index.js"],
      "env": {
        "TIDEPOOLS_API_TOKEN": "<paste-token-here>",
        "TIDEPOOLS_API_BASE_URL": "http://localhost:3000"
      }
    }
  }
}

The local server calls Tidepools API routes at /api/mcp/<tool-name> using bearer authentication.