Ledger CLI MCP Server

Instructions

Implementation Reference

• main.py:264-266 (handler)

  The handler function for the 'ledger_raw_command' tool. It is registered via the @mcp.tool decorator and executes the raw ledger command by delegating to the run_ledger helper function.

  @mcp.tool(description="Run a raw ledger command")
  def ledger_raw_command(params: LedgerRawCommand) -> str:
      return run_ledger(params.command)

• main.py:102-103 (schema)

  Pydantic input schema for the ledger_raw_command tool, defining the required 'command' field as a list of strings for raw ledger arguments.

  class LedgerRawCommand(BaseModel):
      command: List[str] = Field(..., description="Raw ledger command arguments")

• main.py:107-129 (helper)

  Helper utility function to execute arbitrary ledger CLI commands securely via subprocess, with input validation, error handling, and ledger file path management. Directly invoked by the ledger_raw_command handler.

  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