Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ledgerkit-mcp Record sale #1001: $108.75 to cash, $100 to revenue, $8.75 to tax"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that gives AI agents a double-entry ledger they cannot unbalance. Built on ledgerkit.
Agents are increasingly asked to touch money: record a sale, apply a refund, split a commission, reconcile a day. The failure mode is never that the model can't format a journal entry. It's that agents retry, and retries double-post; that models do decimal arithmetic in their heads, and drift; that "fix the balance" is one hallucinated tool call away from rewriting history. This server is a case study in designing tools for that caller: the invariants live below the tool surface, where no prompt can reach them.
Tool | What it does |
| Open an account (asset, liability, equity, income, expense) with an explicit overdraft policy |
| Post a balanced entry: debits must equal credits, |
| Current or point-in-time balance of one account |
| Every account with type, policy, and balance |
| The journal, newest first, paginated with a cursor |
| Every balance plus proof the books balance |
| Split an amount by ratios without losing a penny |
Related MCP server: Agent Ledger
There is no update, no delete, no "set balance", no unbalanced write. Corrections are reversal entries, the same as a real ledger. The agent cannot break an invariant because no tool exists that could: safety by construction beats safety by prompt.
These are the decisions this repo exists to demonstrate.
1. Idempotency is required, not polite. Agents retry. Tool calls time out and get reissued, sessions resume, contexts compact and replay. post_entry requires an idempotency_key tied to the real-world event (order id, webhook event id), so every retry is a safe no-op that returns replayed: true. The same key with different contents is a loud conflict, never a silent overwrite. This survives server restarts, because the key index is rebuilt from the journal.
2. Errors are prompts. A rejected call returns a message written for the model that caused it: which rule was violated, with the numbers (debits 100.00 != credits 10.00), so the next attempt can be correct instead of merely different. An agent that gets "leg amounts must be positive; express direction with the side, not the sign" fixes itself. An agent that gets 400 Bad Request flails.
3. Reads respect the context window. list_entries paginates newest-first with a hard cap and a before_seq cursor. "Return the whole journal" stops being a plan around entry #500, and a tool that can flood the caller's context is a tool that degrades the caller.
4. The model should never do the arithmetic. allocate("100.00", [1,1,1]) returns ["33.34", "33.33", "33.33"], summing to exactly the original (largest-remainder method). Penny-perfect division is precisely the operation language models get plausibly wrong, so it's a tool, not a mental math exercise.
5. The journal is the only truth. Persistence is one append-only JSONL file. On boot, history replays through the same post() path as live traffic, so a tampered or damaged journal refuses to load rather than loading wrong. Balances are derived state, recomputable from the journal at any moment, which is also how point-in-time balances work.
git clone https://github.com/themusashimaru/ledgerkit-mcp
cd ledgerkit-mcp && npm installClaude Code:
claude mcp add ledger \
--env LEDGER_FILE=$HOME/.ledgerkit/journal.jsonl \
-- npx tsx /ABSOLUTE/PATH/TO/ledgerkit-mcp/src/server.tsAny MCP host, same shape:
{
"mcpServers": {
"ledger": {
"command": "npx",
"args": ["tsx", "/ABSOLUTE/PATH/TO/ledgerkit-mcp/src/server.ts"],
"env": { "LEDGER_FILE": "/Users/you/.ledgerkit/journal.jsonl" }
}
}
}Configuration is two environment variables: LEDGER_CURRENCY (USD default, EUR, JPY, or CODE:decimals) and LEDGER_FILE (path to the journal; unset means in-memory, which is fine for a demo and wrong for anything real).
Then ask your agent to keep books:
"Open cash, revenue, and sales_tax_payable accounts. Record today's sale #1001: $108.75 collected, $100 revenue, $8.75 tax. Then show me the trial balance."
npm test # 17 tests over the real MCP protocol (in-memory transport)
npm run smoke # spawns the real stdio server, posts, restarts it, retriesThe suite calls tools through an actual MCP client, not the handlers directly, because schema validation is half the contract. The smoke test kills the server mid-flow and proves a retried post_entry after reboot is a replay, not a double post.
The engine (src/engine/) is vendored from ledgerkit, a zero-dependency double-entry ledger: balanced-by-construction entries, bigint minor-unit money, append-only journal, idempotent posting. This repo is the agent-facing skin around it. The layering is the point: the engine enforces what must be true, the MCP layer decides what a language model should be allowed to ask for and how it should fail.
MIT
Split an amount by integer ratios without losing a minor unit (largest-remainder method). allocate("100.00", [1,1,1]) is ["33.34","33.33","33.33"]: the parts sum to EXACTLY the original. Use this for commission splits, installments, and tax apportionment instead of doing division yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Decimal string in USD, e.g. "100.00" | |
| ratios | Yes | Integer weights, e.g. [50, 30, 20] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It transparently discloses the algorithm (largest-remainder method), the exact-sum guarantee, and gives a concrete example showing the output. It does not cover edge cases like all-zero ratios, but for a simple tool this is sufficient; notably it clearly indicates the splitting behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first defines the behavior and method, the second provides an instant example and use cases. Every word earns its place; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter, no-output-schema tool, the description covers the core algorithm, exactness property, a concrete input-output pair, and explicit use cases. This is fully sufficient for an agent to invoke it correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, meaning both amount and ratios already have descriptions. The description reinforces with an example and clarifies the interpretation, but does not add substantive new semantic detail beyond the schema. This fits the baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a specific verb ('Split an amount') and resource ('an amount by integer ratios'), immediately distinguishing it from sibling financial tools like get_balance or list_entries. The largest-remainder method and exact-sum property further clarify its unique function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states use cases: 'commission splits, installments, and tax apportionment' and provides the alternative 'instead of doing division yourself.' This gives clear when-to-use guidance even without naming a specific sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current signed normal balance of one account (asset/expense: debit-positive; liability/equity/income: credit-positive). Pass as_of for the balance at a past moment, recomputed from the journal.
| Name | Required | Description | Default |
|---|---|---|---|
| as_of | No | ISO 8601 moment for a point-in-time balance | |
| account | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior. It adds useful context about the signed normal balance and that as_of recomputes from the journal, but it does not explicitly state that the tool is read-only or describe error behavior if the account does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and adds the sign convention and as_of explanation without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description covers the core semantics and point-in-time behavior. However, it does not mention the return format (e.g., numeric value) or error cases, which would be more important given no output schema and no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The as_of parameter is well-described in both the schema and description, but the required account parameter has no schema description and the description only says 'one account' without clarifying whether it expects an account name, ID, or other identifier. This leaves a significant gap for the required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the current signed normal balance of a single account, and specifies the sign convention for different account types. This distinguishes it from sibling tools like trial_balance (which likely provides aggregate balances) and list_accounts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for querying a single account balance and mentions using as_of for historical balances, but it does not explicitly contrast with alternative tools or state when not to use it. The context is clear but no exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every account with its type, overdraft policy, and current balance.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the output content (type, overdraft policy, balance) but does not explicitly state whether this is a read-only operation, whether filtering or ordering applies, or any limitations. It is adequate for a simple listing tool but lacks explicit safety or behavior notes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, straightforward sentence that conveys all necessary information without any wasted words. It is highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless listing tool with no output schema, the description provides sufficient context: it names the resource and the three key attributes returned. It lacks explicit alternatives or caveats, but given the simplicity, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline of 4 applies. The description correctly focuses on the returned data rather than parameter details, which is appropriate since there is nothing to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns every account along with type, overdraft policy, and current balance. It is specific and implies listing all accounts, distinguishing it from sibling tools like get_balance or list_entries, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: it should be used when you need a comprehensive list of all accounts and their key attributes. However, there is no explicit guidance on when to prefer this over sibling tools or any exclusions, though the context makes it reasonably obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Journal entries, newest first, paginated. Use before_seq from the previous page to walk further back instead of asking for everything: the journal is append-only and can be long.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, default 20, max 100 | |
| before_seq | No | Only entries with seq strictly below this |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the journal is append-only, entries are ordered newest first, and that pagination is supported via before_seq. This gives the agent critical behavioral context without any safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, perfectly sized. The first sentence states the core purpose; the second provides crucial usage guidance. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers usage, ordering, and pagination well. However, without an output schema, it doesn't describe what fields each journal entry contains (beyond implying seq). This is a minor gap given the simplicity of the tool and the strong guidance provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters with descriptions (100% coverage). The description adds value by explaining how before_seq is used (from the previous page) and why it matters (append-only, long journal), going beyond the schema's basic type and constraint info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists journal entries with specific ordering (newest first) and pagination. This distinguishes it from sibling tools like post_entry, get_balance, and list_accounts, which serve different resources or actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use pagination ('when walking further back'), and explicitly advises against asking for everything at once. Also explains the append-only nature that justifies this usage pattern.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a ledger account. Every account posts in the ledger currency. Accounts may not go negative unless allow_negative is set: overdraft is a policy you opt into, not an accident.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Account id, e.g. "cash" or "sales_tax_payable" | |
| type | Yes | Determines the normal balance side: asset/expense are debit-normal, the rest credit-normal | |
| allow_negative | No | Whether this account's balance may go negative (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals two important behaviors: all accounts post in the ledger currency (single-currency constraint) and accounts may not go negative unless allow_negative is set, framing overdraft as an intentional policy. This provides meaningful context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and every sentence earns its place. It is concise without sacrificing key behavioral constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and only three simple parameters, the description covers the essential behavioral constraints (single currency, negative balance policy). It does not mention error cases like duplicate account IDs, but for a simple creation tool, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add meaningful parameter-level detail beyond what the schema already explains; it only restates the allow_negative policy in prose, which is already captured in the schema description. No new syntax or format guidance is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Open a ledger account.' It also adds context about ledger currency and negative balance policy, which distinguishes it from sibling tools like get_balance, post_entry, and list_accounts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied rather than explicit; the description implies this tool is for creating accounts but does not explicitly state when to use it versus alternatives. No exclusions or alternative tool references are provided, so guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Post a balanced journal entry: total debits must equal total credits across at least two legs. This is the ONLY way to change a balance. Corrections are reversal entries, never edits. If you are retrying a call that may already have gone through, reuse the SAME idempotency_key: you will get the original entry back with replayed=true instead of posting twice.
| Name | Required | Description | Default |
|---|---|---|---|
| legs | Yes | ||
| timestamp | No | Effective time (ISO 8601). Defaults to now. Drives point-in-time balances. | |
| description | Yes | What happened, e.g. "sale #1001" | |
| idempotency_key | Yes | Required dedupe key unique to this real-world event (an order id, webhook event id, invoice number). Reuse it on retries; never reuse it for a different entry. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and delivers substantial behavioral context. It discloses the balanced-entry invariant, the two-leg minimum, the reversal-not-edit rule, and the idempotent retry behavior (returning original entry with replayed=true). This is far more transparent than typical descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the primary purpose, then key constraints, then retry guidance. Every sentence provides unique value with no redundancy or fluff. The structure is logical and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description covers the essential operational aspects: how to construct legs, the balancing invariant, idempotency behavior, and the correction policy. It could go slightly further by stating the normal success return value, but the mention of replayed=true on retries implicitly covers the response shape. Overall, it is complete enough for an agent to confidently invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all parameters with high coverage (75%+), so the baseline is 3. The description adds significant meaning beyond the schema by explaining the balancing requirement for legs, the correct use of idempotency_key on retries, and the distinction between direction and sign for amounts. This elevates the score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Post a balanced journal entry' – a specific verb and resource – and immediately states the core accounting constraint (debits equal credits across at least two legs). It further differentiates the tool by asserting it is 'the ONLY way to change a balance,' distinguishing it from sibling read/query tools and the allocate tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: this is the only way to change a balance, corrections must be made as reversal entries rather than edits, and retries should reuse the same idempotency_key. This informs the agent when to use the tool and how to handle failure/recovery scenarios, going beyond generic alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every account's balance plus the proof the books balance: total debits and total credits across the whole journal, always equal.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the output contents (account balances, total debits/credits, equality) but does not mention side effects, read-only nature, or any constraints. This is adequate for a report tool but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, but uses a colon to introduce the proof of balance, which is slightly awkward yet still concise. Every phrase conveys essential information without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description explains the return values well: per-account balances, total debits, total credits, and the guarantee of equality. It is complete enough for a simple report tool, though it omits details like time period or formatting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description adds meaning by explaining what the report contains, which compensates for the lack of parameter documentation. No parameter details are needed here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: generating a trial balance showing every account's balance plus total debits and credits. This distinguishes it from sibling tools like get_balance (single account) and list_accounts (account listing) by emphasizing the equality proof.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives. It does not mention scenarios like checking ledger balance or when to use get_balance instead, leaving the agent to infer usage from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0allocateget_balancelist_accountslist_entriesopen_accountpost_entrytrial_balanceScored across 7 tools
Each tool targets a distinct action or resource: account querying, creation, entry posting, listing, reporting, and allocation. No two tools could be confused for the same operation, even with overlapping concepts like balance and trial balance.
The vast majority follow a clear verb_noun pattern (get_, open_, post_, list_). allocate is a single verb, and trial_balance is a noun phrase, but the all-lowercase underscore style and intuitive verbs keep the set predictable.
At 7 tools, the server covers the core ledger lifecycle (accounts, entries, reports) plus a useful allocation utility. It feels appropriately scoped without redundancy or excess.
The tool set covers opening/listing accounts, posting/listing entries, querying balances, and producing a trial balance. Minor gaps like fetching a single entry or account details are workable through list endpoints, and the append-only design intentionally omits deletion/editing.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Personal finance ledger for AI agents — query spending, track bills, forecast cash flow.
Personal-finance workspace for AI agents: accounts, spending, budgets, goals, and investments.
Agent-native double-entry accounting ledger with x402 micropayments
AI agents for bookkeeping, reconciliation, and financial close for SMBs.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/themusashimaru/ledgerkit-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
