Ledger CLI MCP Server

Instructions

Implementation Reference

• main.py:188-195 (handler)

  The handler function for the 'ledger_accounts' tool. It constructs the 'ledger accounts' command with an optional query filter and executes it via the run_ledger helper. Registered using the @mcp.tool decorator.

  @mcp.tool(description="List all accounts")
  def ledger_accounts(params: LedgerAccounts) -> str:
      cmd = ["accounts"]
  
      if params.query:
          cmd.append(params.query)
  
      return run_ledger(cmd)

• main.py:58-60 (schema)

  Pydantic BaseModel schema for input parameters to the ledger_accounts tool, defining an optional query string for filtering accounts.

  class LedgerAccounts(BaseModel):
      query: Optional[str] = Field(None, description="Filter accounts by regex pattern")

• main.py:188-188 (registration)

  The @mcp.tool decorator registers the ledger_accounts function as an MCP tool with the description 'List all accounts'.

  @mcp.tool(description="List all accounts")

• main.py:107-129 (helper)

  Shared helper function that runs ledger CLI commands securely, used by ledger_accounts and other tools.

  def run_ledger(args: List[str]) -> str:
      try:
          if not LEDGER_FILE:
              return "Ledger file path not set. Please provide it via --ledger-file argument or LEDGER_FILE environment variable."
  
          # Validate inputs to prevent command injection
          for arg in args:
              if ";" in arg or "&" in arg or "|" in arg:
                  return "Error: Invalid characters in command arguments."
  
          result = subprocess.run(
              ["ledger", "-f", LEDGER_FILE] + args,
              check=True,
              text=True,
              capture_output=True,
          )
          return result.stdout
      except subprocess.CalledProcessError as e:
          error_message = f"Ledger command failed: {e.stderr}"
          if "couldn't find file" in e.stderr:
              error_message = f"Ledger file not found at {LEDGER_FILE}. Please provide a valid path via --ledger-file argument or LEDGER_FILE environment variable."
          return error_message