VoiceLedger

"Talk money. It listens." — a voice-first personal finance ledger for the Alexa+ track of the Amazon App Dev Hackathon 2026.

VoiceLedger is a self-hosted MCP server (Streamable HTTP, MCP spec 2025-11-25+) that turns spoken money updates into a real ledger: log expenses by voice, get auto-categorization, budget alerts, and AI spending insights powered by Amazon Bedrock — with a fully working offline fallback so the demo never breaks.

Quick start

cd voiceledger
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Configure (all secrets via environment, never committed)
export API_TOKEN=<redacted>
export LEDGER_DB="data/ledger.db"        # default
export BEDROCK_MODEL_ID=""               # empty = offline fallback mode
export BEDROCK_REGION="ap-south-1"

# Optional: seed a month of realistic INR demo data
python scripts/seed_demo.py

# Start the server
python -m server.server
# MCP endpoint: http://127.0.0.1:8000/mcp
# Health:       http://127.0.0.1:8000/healthz

Open demo/index.html in a browser for the simulated Alexa+ voice console. Set the token field to your API_TOKEN and press Reconnect.

Related MCP server: Expense Tracker MCP Server

MCP tools

All tool outputs are short, speakable sentences — no markdown, no tables.

Protocol smoke test (curl) ```bash TOKEN=your-token-here SID=$(curl -s -D - -o /tmp/init -X POST http://127.0.0.1:8000/mcp \ -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \ | grep -i mcp-session-id | awk '{print $2}' | tr -d '

') curl -s -X POST http://127.0.0.1:8000/mcp -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -H "Mcp-Session-Id: $SID" \ -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' -o /dev/null -w '%{http_code} ' curl -s -X POST http://127.0.0.1:8000/mcp -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -H "Mcp-Session-Id: $SID" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | grep -o '"name":"[^"]"' curl -s -X POST http://127.0.0.1:8000/mcp -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -H "Mcp-Session-Id: $SID" \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"log_expense","arguments":{"amount":450,"note":"groceries"}}}' \ | grep -o 'data: .' ``` ## Run the tests

pytest -q

28 tests: ledger logic, budget alerts, undo, offline categorizer, tool outputs, and a full protocol smoke test against a live server subprocess.

Bedrock integration

Set BEDROCK_MODEL_ID (e.g. anthropic.claude-3-5-sonnet-20240620-v1:0) and provide AWS credentials in the standard way (~/.aws/credentials, AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, or an IAM role). The server uses the converse API for expense categorization and monthly spending insights. If the model is unset or any AWS call fails, brain.py transparently falls back to the deterministic rule-based categorizer and template insights — the demo works with zero AWS setup.

Project layout

server/        MCP server (mcp SDK), SQLite ledger, Bedrock brain, Bearer <redacted>
demo/          simulated Alexa+ voice console (static HTML, talks to /mcp)
tests/         pytest suite (28 tests)
scripts/       seed_demo.py — one month of realistic INR transactions

License

MIT — see LICENSE.