Notion Household Finance

Codex plugin and local MCP server for managing a Notion-backed household finance workspace.

This repository is designed for a personal Notion setup with Korean household-finance databases. It provides deterministic Notion API tools for querying and writing finance records, while keeping secrets and data source IDs outside the repository.

What This Includes

• A Codex plugin manifest at .codex-plugin/plugin.json
• A local MCP server at scripts/mcp_server.mjs
• A small CLI at scripts/notion_household_finance.mjs
• A Codex skill at skills/notion-household-finance/SKILL.md
• Example config files under examples/

Requirements

• Node.js 20 or newer
• A Notion integration token with access to the target databases
• A local data source config file
• Codex plugin support

Configuration

Create a local config file. The default location is:

~/.config/household-finance/config.json

Use examples/config.example.json as the shape:

{
  "databases": {
    "monthly_budget": "notion-data-source-id",
    "fixed_expense": "notion-data-source-id",
    "income_expense": "notion-data-source-id",
    "debt": "notion-data-source-id",
    "repayment": "notion-data-source-id",
    "savings_goal": "notion-data-source-id",
    "savings_record": "notion-data-source-id",
    "investment": "notion-data-source-id",
    "spending_limit": "notion-data-source-id"
  }
}

Set these environment variables on the machine that will run Codex:

export NOTION_TOKEN="secret_notion_token_here"
export NOTION_VERSION="2026-03-11"

Optional:

export HOUSEHOLD_FINANCE_CONFIG="/absolute/path/to/config.json"

Do not commit .env, local config files, Notion tokens, or real data source IDs.

Install As A Personal Codex Plugin

Clone this repo into the personal plugin directory:

mkdir -p ~/.agents/plugins/plugins
git clone https://github.com/atototo/notion-household-finance.git ~/.agents/plugins/plugins/notion-household-finance

Create or update ~/.agents/plugins/marketplace.json using examples/marketplace.example.json as the shape. The important plugin source path is:

{
  "source": {
    "source": "local",
    "path": "./plugins/notion-household-finance"
  }
}

After Codex reloads plugins, the plugin should appear as notion-household-finance@personal.

CLI Usage

Inspect a configured data source:

node scripts/notion_household_finance.mjs inspect-data-source income_expense

Query a configured data source:

node scripts/notion_household_finance.mjs query-data-source income_expense --page-size 10

Create a raw page:

node scripts/notion_household_finance.mjs create-page income_expense --properties-json '{"내역":{"title":[{"type":"text","text":{"content":"테스트"}}]}}'

MCP Tools

The plugin exposes these MCP tools when loaded by Codex:

• notion_hf_health_check
• notion_hf_inspect_data_source
• notion_hf_query_data_source
• notion_hf_create_page
• notion_hf_find_monthly_budget
• notion_hf_create_monthly_budget
• notion_hf_create_variable_spending_limits
• notion_hf_record_transaction
• notion_hf_record_repayment
• notion_hf_record_savings

Security

This repository should not contain:

• Notion tokens
• Real .env files
• Real personal finance exports
• Private Notion page IDs unless you intentionally keep the repo private

Before publishing, run a local secret scan or inspect the diff manually.