list_transactions
Retrieve stored financial transactions with pagination and category filtering to analyze spending patterns and track portfolio allocations.
Instructions
List stored transactions from the JSON ledger with optional pagination and filtering.
Args:
limit: Maximum number of transactions to return (default 20)
offset: Number of transactions to skip from the beginning (default 0)
category: Optional category filter (case-insensitive)
Returns:
Dictionary containing total count, pagination info, and transactions with index fieldInput Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| category | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- my_finance_mcp.py:135-167 (handler)The `list_transactions` tool handler function. It is registered via the `@mcp.tool()` decorator. Loads transactions from JSON, filters by optional category, adds indices, applies pagination (offset/limit), and returns structured dictionary with totals and pagination info.
@mcp.tool() def list_transactions(limit: int = 20, offset: int = 0, category: Optional[str] = None) -> Dict[str, Any]: """ List stored transactions from the JSON ledger with optional pagination and filtering. Args: limit: Maximum number of transactions to return (default 20) offset: Number of transactions to skip from the beginning (default 0) category: Optional category filter (case-insensitive) Returns: Dictionary containing total count, pagination info, and transactions with index field """ transactions = _load_transactions() indexed: List[Dict[str, Any]] = [] for idx, txn in enumerate(transactions): if category and str(txn.get("category", "")).lower() != category.lower(): continue entry = dict(txn) entry["index"] = idx indexed.append(entry) total = len(indexed) sliced = indexed[offset: offset + limit] return { "total": total, "offset": offset, "limit": limit, "transactions": sliced, "has_more": offset + limit < total } - my_finance_mcp.py:27-35 (helper)Helper utility to load the list of transactions from the persistent JSON file, used directly in `list_transactions`.
def _load_transactions() -> List[Dict[str, Any]]: if JSON_FILE.exists(): with JSON_FILE.open("r") as f: try: return json.load(f) except json.JSONDecodeError: return [] return [] - my_finance_mcp.py:135-135 (registration)The `@mcp.tool()` decorator registers the `list_transactions` function as an MCP tool.
@mcp.tool()