Skip to main content
Glama
Firefly III MCP Server

Firefly III MCP Server

by edmondxie779

Create Transaction

create_transaction

Record expenses, income, and transfers in Firefly III, including multi-split transactions, by specifying account, date, amount, and type.

Instructions

Record a new transaction (or multi-split transaction group) in Firefly III.

  • For an expense ('withdrawal'): specify your asset account via 'source_id' or 'source_name', and the merchant via 'destination_name' (or 'destination_id').

  • For income ('deposit'): specify the payer/revenue source via 'source_name' (or 'source_id'), and your asset account via 'destination_id' or 'destination_name'.

  • For a transfer ('transfer'): specify both 'source_id'/'source_name' and 'destination_id'/'destination_name' pointing to two of your own asset/liability accounts.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "transactions": "<transactions>"
    },
    "name": "create_transaction"
  }
}

Input Schema

NameRequiredDescriptionDefault
apply_rulesNoWhether Firefly III automation rules should run on this transaction.
group_titleNoTitle for the transaction group (recommended when creating a multi-split transaction).
transactionsYesOne split for a standard transaction, or multiple splits (all sharing the same 'type') for a split transaction.
fire_webhooksNoWhether Firefly III webhooks should fire for this transaction.
error_if_duplicate_hashNoSet true to reject the transaction if an identical transaction hash already exists.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false, so the write/non-destructive profile is covered. The description adds little beyond that: it omits that duplicate detection is off by default, that automation rules and webhooks fire by default as side effects, and what happens on validation failure. Those behaviors are documented only in parameter schemas, not in the prose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence establishes the action, then three tight bullets keyed by transaction type. No filler, no repetition of schema text, and the highest-risk information (which field means what) comes first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a nested write tool with a required array of splits and ~20 per-split properties, the description covers the semantics an agent most needs. The remaining gap is the return contract: with no output schema, the description never says whether a created transaction/group ID is returned and how to retrieve it afterwards.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely relational meaning the per-parameter schema cannot express: the same source/destination fields mean different things depending on 'type'. That cross-field mapping is the main source of misuse risk and is well handled; apply_rules, fire_webhooks, group_title, and error_if_duplicate_hash are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'Record a new transaction (or multi-split transaction group) in Firefly III' — and immediately scopes it by transaction type. It is instantly distinguishable from siblings such as update_transaction, delete_transaction, and create_account without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives per-type conditional instructions: withdrawals need your asset account as source and the merchant as destination, deposits invert this, transfers require two of your own accounts. That is real when-to-use guidance, but it never addresses sequencing against siblings (e.g. use search_accounts first, or update_transaction to correct a mistake), so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.