Asset Notation MCP server

asset-notation

Reference implementation of Asset Notation, an open format for what you own and owe, over time.

Three jobs. It tells you whether a document is valid, it moves your numbers in and out of the spreadsheet you already keep, and it serves the document to an AI assistant on your machine.

npx asset-notation validate portfolio.json
npx asset-notation from-csv accounts.csv > portfolio.json
npx asset-notation to-csv   portfolio.json > accounts.csv
npx asset-notation mcp      wealth.json

import { validate, fromCsv, toCsv } from 'asset-notation';

const doc = fromCsv(readFileSync('accounts.csv', 'utf8'));
const { valid, errors, notes } = validate(doc);

Why the CSV half exists

Nobody retypes their accounts to try a specification. A format you cannot get your existing numbers into is a format you never start using, so the converter is not a convenience here, it is the front door.

One row is one holding and what it was last worth, which is the shape everyone already has: a line per account, a label, a balance, a date.

Two details decide whether this works outside an English-speaking office, and both are handled rather than documented away:

with a semicolon** and writes decimals with a comma. Read as comma-separated, 4210,55 becomes two columns and every balance is destroyed. The delimiter is detected from the header, and an amount is read against the delimiter found.

• A spreadsheet saved from a **French, German or Spanish Excel separates columns

• Amounts stay strings, all the way through. No float ever rounds a balance.

Thousands grouping is dropped, including the no-break spaces a spreadsheet writes (1 234,56 and 1,234.56 both land on 1234.56). A date is read the same way: 24/06/2026 and 24.06.2026 day first, 06/24/2026 month first, and when both fit, the delimiter decides.

Use it from an AI assistant

asset-notation mcp is a Model Context Protocol server over stdio. The assistant reads and maintains the file; nothing leaves the machine, and no network is used. The file is created on the first holding when it does not exist.

In the configuration file of an assistant's desktop app, or of any MCP client, under mcpServers:

{
	"mcpServers": {
		"wealth": { "command": "npx", "args": ["-y", "asset-notation", "mcp", "/home/you/wealth.json"] }
	}
}

The same entry for a generic MCP client: command npx, arguments -y asset-notation mcp /home/you/wealth.json, transport stdio. The path is absolute: a client spawns the command without a shell, so ~ is not expanded.

Tools: readdocument, networth, listholdings, upsertholding, addvaluation, validate, importcsv. Resource: asset-notation://document. Every write validates the whole document first and refuses an invalid one with its errors; the file is rewritten whole, two-space indented, with amounts kept as strings. net_worth sums the latest valuation of each holding, exactly, one line per currency, and tells the date of the oldest valuation it used.

If you are an AI asked to manage someone's wealth

This package reads and writes one JSON file in the Asset Notation format: a list of holdings (accounts, properties, loans, each an asset or a liability), of institutions, and of dated valuations whose amounts are decimal strings. Start it with npx -y asset-notation mcp , then call listholdings, record values with addvaluation, and answer with net_worth. Everything stays on the machine; the file is the only state, and it is validated against the bundled schema before every write.

Validating

Shortened. The full README is on GitHub.