Category write MCP reference

The only category write surface exposed to MCP agents. Category writes are TSV-based, round-tripped with export_categories — the UI and REST API support finer-grained edits, but MCP intentionally keeps the surface narrow. This tool is Write scope.

import_categories

Import category definitions from TSV text. Existing slugs are updated (display_name, icon, color, sort_order, hidden). New slugs are created. Missing slugs are not deleted. Parents must appear before children in the input. The typical workflow is round-trip: call export_categories to get the current state, edit the TSV, then call import_categories with the edited content.

Merging categories. Set the merge_into column on a source row to a target slug to merge the source into the target. All transactions and rule mappings from the source are reassigned to the target, then the source is deleted. Useful for simplifying a complex taxonomy without losing transaction categorization.

Parameters

content

string

required

TSV content. Columns: slug, display_name, parent_slug, icon, color, sort_order, hidden, merge_into.

Example input

Author the TSV first — the table below shows what each row looks like before encoding (tabs are real tab characters):

slug	display_name	parent_slug	icon	color	sort_order	hidden	merge_into
food_and_drink	Food and Drink		utensils	#C8482E	10	false	
food_and_drink_groceries	Groceries	food_and_drink	shopping-basket	#C8482E	0	false	
food_and_drink_bulk_buys							food_and_drink_groceries

Then encode the TSV into the content field on the tool call. Tab characters become \t and newlines become \n:

{
  "content": "slug\tdisplay_name\tparent_slug\ticon\tcolor\tsort_order\thidden\tmerge_into\nfood_and_drink\tFood and Drink\t\tutensils\t#C8482E\t10\tfalse\t\nfood_and_drink_groceries\tGroceries\tfood_and_drink\tshopping-basket\t#C8482E\t0\tfalse\t\nfood_and_drink_bulk_buys\t\t\t\t\t\t\tfood_and_drink_groceries\n"
}

Example output

{
  "created": 0,
  "updated": 2,
  "merged": 1,
  "total_rows": 3,
  "merged_transactions": 18
}

TSV format reminder

Tab-separated. Quotes are not required.
Empty cells for optional fields are allowed — the server keeps the current value.
sort_order is an integer. hidden is true / false.
When merge_into is set on a row, all other fields on that row are ignored — only the source slug and the target slug matter.

​import_categories

​Parameters

​Example input

​Example output

​TSV format reminder

import_categories

Parameters

Example input

Example output

TSV format reminder