mcp-inbox-reader

MCP Server that lets AI agents read your inBox notes from your own S3/WebDAV cloud storage. Local-first, zero server.

Why

inBox is a local-first notes app that syncs via S3 or WebDAV. This MCP server gives AI coding agents (Claude Desktop, Codex, Cursor etc.) direct access to your notes, so they can search, read, and reference your knowledge base while helping you code.

Install

npx mcp-inbox-reader

Or install globally:

npm install -g mcp-inbox-reader

Configuration

Set environment variables to tell the server where your notes live.

S3 (e.g. Bitiful, Cloudflare R2, AWS S3)

CLOUD_TYPE=s3
S3_ENDPOINT=https://s3.bitiful.net
S3_BUCKET=my-inbox-bucket
S3_ACCESS_KEY=your_access_key
S3_SECRET_KEY=your_secret_key
S3_REGION=auto
S3_FORCE_PATH_STYLE=true
WORK_DIR=inBox

WebDAV

CLOUD_TYPE=webdav
WEBDAV_URL=https://your-webdav-server.com/remote.php/dav/files/user
WEBDAV_USERNAME=your_username
WEBDAV_PASSWORD=your_password
WORK_DIR=inBox

| Env | Default | Description | | :--- | :--- | :--- | | CLOUD_TYPE | required | s3 or webdav | | WORK_DIR | inBox | Root folder for notes in cloud storage | | CACHE_TTL_MS | 60000 | Listing cache TTL in ms |

How it works

mcp-inbox-reader connects directly to your S3/WebDAV storage and reads inBox note files as raw JSON. No intermediate server, no database — your notes never leave your own cloud.

AI agent (Claude / Codex)
        ↓ MCP stdio
  mcp-inbox-reader
        ↓ S3 ListObjects / WebDAV PROPFIND
  your cloud storage

Caching: notes are loaded into memory once and cached for 60 seconds (configurable via CACHE_TTL_MS). Within that window, asking "search notes", "list recent", and "read note" all hit the same cache — zero extra API calls to your cloud storage. After 60 seconds, the next request triggers a fresh load.

Request dedup: if the cache expires and multiple requests come in at once, only one fetch goes out to S3/WebDAV — the others wait and share the result.

Read + Write: read_note, list_notes, search_notes, and list_tags are read-only. create_note writes new note JSON files to your cloud storage — your inBox app will pick them up on the next sync.

MCP Client Setup

Claude Desktop

{
  "mcpServers": {
    "inbox-reader": {
      "command": "npx",
      "args": ["-y", "mcp-inbox-reader"],
      "env": {
        "CLOUD_TYPE": "s3",
        "S3_ENDPOINT": "https://s3.bitiful.net",
        "S3_BUCKET": "my-inbox-bucket",
        "S3_ACCESS_KEY": "xxx",
        "S3_SECRET_KEY": "xxx",
        "S3_REGION": "auto",
        "S3_FORCE_PATH_STYLE": "true"
      }
    }
  }
}

Codex

{
  "mcpServers": {
    "inbox-reader": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-inbox-reader"],
      "env": {
        "CLOUD_TYPE": "s3",
        "S3_ENDPOINT": "https://s3.bitiful.net",
        "S3_BUCKET": "my-inbox-bucket",
        "S3_ACCESS_KEY": "xxx",
        "S3_SECRET_KEY": "xxx",
        "S3_REGION": "auto",
        "S3_FORCE_PATH_STYLE": "true"
      }
    }
  }
}

Tools

| Tool | Description | | :--- | :--- | | list_notes | List note summaries with optional time range and date field filtering | | read_note | Read full content of a single note by ID | | search_notes | Search notes by keyword in title/body/tags | | list_tags | List all tags across notes | | create_note | Create a new note (AI agent writes to your inBox) | | update_note | Update an existing note by ID (partial update, only changed fields) | | delete_note | Soft-delete a note (marks is_removed=true, client sync cleans up) |

License

MIT