Kakeibo MCP Server

Read-only MCP server for connecting AI clients to the Kakeibo Public Developer API.

Phase 1 exposes personal me scope tools only. It can inspect profile, usage, currencies, accounts, categories, tags, transactions, and reports. It does not create, update, void, delete, upload, or otherwise mutate Kakeibo data.

This package is MIT licensed. The Kakeibo application, backend, and hosted services remain proprietary.

Requirements

• Node.js 20+
• A Kakeibo Solo or Family account
• A Kakeibo Public API key created in the dashboard under Settings -> Developer
• An MCP-compatible client that can launch local stdio servers

Do not commit API keys. Pass them through environment variables or your local MCP client configuration.

Configuration

| Variable | Description | |---|---| | KAKEIBO_API_BASE_URL | Kakeibo API origin, for example https://api.kakei.io | | KAKEIBO_API_KEY | Public API key from Settings -> Developer |

For production use:

export KAKEIBO_API_BASE_URL="https://api.kakei.io"
export KAKEIBO_API_KEY="kak_xxxxxxxxxxxxxxxxxxxxxxxx"

For local backend development, use your Laravel API origin, for example http://localhost:8000. Do not include /api/public/v1; the server adds that path internally.

Install with npx

Most users should run the published npm package directly from their MCP client configuration:

{
  "mcpServers": {
    "kakeibo": {
      "command": "npx",
      "args": ["-y", "kakeibo-mcp-server"],
      "env": {
        "KAKEIBO_API_BASE_URL": "https://api.kakei.io",
        "KAKEIBO_API_KEY": "kak_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart your MCP client after updating its configuration.

Local Development

Install dependencies from the repository root:

pnpm install

Run typecheck, build, and tests:

pnpm --filter kakeibo-mcp-server typecheck
pnpm --filter kakeibo-mcp-server build
pnpm --filter kakeibo-mcp-server test

Start the server in development mode:

KAKEIBO_API_BASE_URL="http://localhost:8000" \
KAKEIBO_API_KEY="your-public-api-key" \
pnpm --filter kakeibo-mcp-server dev

Build and run the compiled server:

pnpm --filter kakeibo-mcp-server build

KAKEIBO_API_BASE_URL="http://localhost:8000" \
KAKEIBO_API_KEY="your-public-api-key" \
pnpm --filter kakeibo-mcp-server start

Local MCP Client Configuration

When developing from a local checkout, point your MCP client at the built server entrypoint:

{
  "mcpServers": {
    "kakeibo": {
      "command": "node",
      "args": ["/absolute/path/to/kakeibo/apps/mcp-server/dist/index.js"],
      "env": {
        "KAKEIBO_API_BASE_URL": "http://localhost:8000",
        "KAKEIBO_API_KEY": "your-public-api-key"
      }
    }
  }
}

Use an absolute path for dist/index.js. Rebuild after code changes.

Publishing

Run these checks before publishing:

pnpm --filter kakeibo-mcp-server typecheck
pnpm --filter kakeibo-mcp-server build
pnpm --filter kakeibo-mcp-server test
pnpm --filter kakeibo-mcp-server exec npm pack --dry-run

Publish from the package directory after confirming the packed files:

cd apps/mcp-server
npm publish --access public

Tools

| Tool | Purpose | |---|---| | get_current_user | Get user profile and plan context | | get_usage | Inspect plan usage and quotas | | list_currencies | List supported currencies | | list_accounts | List accounts and balances | | list_categories | List transaction categories | | list_tags | List transaction tags | | search_transactions | Search and filter transactions | | get_transaction | Fetch a transaction by id | | get_total_spending_report | Get income, expense, and net totals | | get_categories_spending_report | Get spending grouped by category | | get_spending_trends | Get spending trend time series | | get_dashboard_report | Get combined report data |

Report tools return Kakeibo Public API output as-is. Multi-currency totals may be limited while converted_amount = amount in the backend.

Example Prompts

• Show my spending by category this month.
• Find my largest expenses this year.
• List my recent transactions for the default account.
• How close am I to my plan limits?
• Summarize my income and expenses for last month.

Smoke Test

1. Start the Laravel API locally and confirm the Public Developer API is reachable.
2. Create a Public API key in Settings -> Developer.
3. Build this package with pnpm --filter kakeibo-mcp-server build.
4. Configure an MCP client with the stdio command shown above.
5. Ask for profile, reference data, transaction search, and a report.

You can also run the built-in smoke script:

KAKEIBO_API_BASE_URL="http://localhost:8000" \
KAKEIBO_API_KEY="your-public-api-key" \
pnpm --filter kakeibo-mcp-server smoke

Minimum tools to verify:

| Area | Tool | |---|---| | Profile | get_current_user | | Reference data | list_accounts | | Transactions | search_transactions | | Reports | get_dashboard_report |

Phase 2

Mutation tools are planned separately. They will require stricter confirmation behavior and should not be added to Phase 1. Candidate future tools include transaction creation, transaction voiding, account lifecycle changes, category/tag management, and file attachment operations.