Expense MCP

Open-source expense tracker with two parts:

1. A FastMCP server that stores expenses in Postgres (Supabase).

2. An Expo Android app that acts as an MCP host. You can speak or type an expense; Claude calls the MCP tools for you.

Live MCP endpoint:

https://indirect-olive-catshark.fastmcp.app/mcp

Repo: github.com/sahaniaditya/expense-mcp

Features

• add_expense — save an amount, category, date, and optional description

• get_expenses — list expenses in a date range

• data://categories — groceries, transport, education, entertainment, health, other

• Voice input on Android (“I spent 250 on groceries”)

• Horizon / FastMCP Cloud OAuth for the expense server

• Optional Google Calendar and Gmail from the Android app (draft-only Gmail; Meet via Calendar)

• GitHub Actions workflow that builds a standalone APK

Related MCP server: Expense Tracker MCP

Architecture

Android app (MCP host)
  → Claude (Anthropic API)
    → expense MCP (FastMCP Cloud / Horizon)
      → Supabase Postgres
    → Google Calendar API (on-device, after Google sign-in)
    → Gmail API (on-device, draft-only)

The phone app does not talk to the database directly. Claude decides which tool to call; the app runs expense tools against FastMCP Cloud, and Calendar/Gmail tools against Google’s REST APIs on the phone.

MCP server

Requirements

• Python 3.14+

• uv

• A Postgres database (Supabase works)

Database

Create an expenses table:

create table if not exists expenses (
  id uuid primary key,
  price integer not null,
  category text not null,
  date timestamptz not null,
  description text
);

Environment

Copy .env.example to .env and set your connection string:

SUPABASE_URL=postgresql://postgres:YOUR_PASSWORD@db.YOUR_PROJECT.supabase.co:5432/postgres

Never commit .env.

Run locally

uv sync
uv run python main.py

The HTTP MCP endpoint is http://127.0.0.1:8000/mcp.

Inspector:

uv run fastmcp dev inspector main.py

Deploy

Push this repo to GitHub, then create a project on Prefect Horizon / FastMCP Cloud with entrypoint main.py:mcp. Add SUPABASE_URL as a secret in the deployment settings.

Clients connect to:

https://YOUR-PROJECT.fastmcp.app/mcp

Horizon authentication is on by default. Use a Horizon API key (fmcp_...) or complete the OAuth sign-in from a client.

Android app

Source lives in mobile/.

Try with Expo Go (development)

Play Store Expo Go must match SDK 54.

cd mobile
npm install
npx expo start

You still need a computer running Metro. For a phone-only install, use the APK.

App setup

1. Open Connect.

2. Confirm the FastMCP Cloud URL (already prefilled for the hosted server).

3. Paste an Anthropic API key.

4. Tap Sign in and connect and finish Horizon login (or paste a fmcp_ API key).

5. Optional: tap Sign in with Google for Calendar and Gmail tools.

6. Use Speak or Add.

The app stores the session and reconnects on the next launch.

Google Calendar and Gmail

Google’s official Calendar/Gmail MCP servers are a Workspace developer preview and often blocked for personal Gmail. The Android app instead calls the Calendar and Gmail REST APIs on the phone with the signed-in Google token. Expense tools stay on FastMCP Cloud. Calendar/Gmail tools appear after Google sign-in (prefixed calendar__ and gmail__).

Limits

• Gmail can search, read, and create drafts only. It cannot send. After a draft is created, send it from Gmail.

• There is no separate Meet API in the app. Ask to create an event with a Meet link (calendar__create_event with with_meet).

Google Cloud (one-time)

1. Create a GCP project (or reuse one).

2. Enable the product APIs:

gcloud services enable \
  calendar-json.googleapis.com \
  gmail.googleapis.com \
  --project=YOUR_PROJECT_ID

3. Configure the OAuth consent screen (External is fine for a personal app). Add yourself as a test user.

4. Add scopes:

   • https://www.googleapis.com/auth/calendar.calendarlist.readonly

   • https://www.googleapis.com/auth/calendar.events.freebusy

   • https://www.googleapis.com/auth/calendar.events.readonly

   • https://www.googleapis.com/auth/calendar.events

   • https://www.googleapis.com/auth/gmail.readonly

   • https://www.googleapis.com/auth/gmail.compose

5. Create an OAuth client of type Web application.

6. Do not use auth.expo.io or expensemcp://google. Gmail and Calendar are sensitive scopes, so Google blocks Expo’s proxy (expo.io has not completed the Google verification process).

   • Authorized JavaScript origins: https://sahaniaditya.github.io

   • Authorized redirect URIs: https://sahaniaditya.github.io/expense-mcp/oauth-callback.html

7. On the OAuth consent screen Audience, add your Gmail (adityasahani93@gmail.com or whatever you sign in with) as a test user. The app stays in Testing until Google verifies it.

8. Enable GitHub Pages on this repo (Settings → Pages → Deploy from main, folder /docs) so that callback URL exists. The page is docs/oauth-callback.html.

9. expo.extra.googleRedirectUri in mobile/app.json must match the Google Cloud redirect URI exactly.

10. In the app Connect tab, paste the Google web client ID and secret, then tap Sign in with Google. They are stored on the phone, not in git.

OAuth apps left in Testing expire refresh tokens after 7 days. Re-sign in, or publish the OAuth app.

App setup (Google)

1. Connect tab → paste Google web client ID and secret.

2. Tap Sign in with Google.

3. Connect tab → Sign in with Google.

4. Confirm Calendar and Gmail show as connected and their tools appear in the list.

Build an APK

GitHub Actions produces a release APK (JS bundle included, no Metro required):

1. Push to main or apk-github-actions, or run the Android APK workflow from the Actions tab.

2. Download the expense-mcp-apk artifact.

3. Unzip and install app-release.apk.

4. Uninstall any previous debug build first.

Local EAS (optional, needs an Expo account):

cd mobile
npx eas-cli login
npx eas-cli build -p android --profile preview

Project layout

main.py              Expense MCP tools and resource
connection.py        Supabase / Postgres connection
mobile/              Expo SDK 54 Android MCP host
mobile/src/mcpHost.ts  Routes tools to expense, Calendar, and Gmail MCP servers
.github/workflows/   APK build

License

MIT. See LICENSE.