Norman Finance MCP Server

Instructions

Search for transactions matching specified criteria.

Args:
    description: Text to search for in transaction descriptions
    from_date: Start date in YYYY-MM-DD format
    to_date: End date in YYYY-MM-DD format
    min_amount: Minimum transaction amount
    max_amount: Maximum transaction amount
    category: Transaction category
    limit: Maximum number of results to return (default 100)
    no_invoice: Whether to exclude invoices
    no_receipt: Whether to exclude receipts
    status: Status of the transaction (UNVERIFIED, VERIFIED)
    cashflow_type: Cashflow type of the transaction (INCOME, EXPENSE)
Returns:
    List of matching transactions with sensitive data removed

Implementation Reference

• norman_mcp/tools/transactions.py:15-85 (handler)

  The core handler function for the 'search_transactions' tool. It uses @mcp.tool() decorator for registration, defines input schema with Pydantic Fields, and implements the logic to query the Norman Finance API for matching transactions based on provided filters.

  @mcp.tool()
  async def search_transactions(
      ctx: Context,
      description: Optional[str] = Field(description="Text to search for in transaction descriptions"),
      from_date: Optional[str] = Field(description="Start date in YYYY-MM-DD format"),
      to_date: Optional[str] = Field(description="End date in YYYY-MM-DD format"),
      min_amount: Optional[float] = Field(description="Minimum transaction amount"),
      max_amount: Optional[float] = Field(description="Maximum transaction amount"),
      category: Optional[str] = Field(description="Transaction category"),
      no_invoice: Optional[bool] = Field(description="Whether to exclude invoices"),
      no_receipt: Optional[bool] = Field(description="Whether to exclude receipts"),
      status: Optional[str] = Field(description="Status of the transaction (UNVERIFIED, VERIFIED)"),
      cashflow_type: Optional[str] = Field(description="Cashflow type of the transaction (INCOME, EXPENSE)"),
      limit: Optional[int] = Field(description="Maximum number of results to return (default 100)")
  ) -> Dict[str, Any]:
      """
      Search for transactions matching specified criteria.
      
      Args:
          description: Text to search for in transaction descriptions
          from_date: Start date in YYYY-MM-DD format
          to_date: End date in YYYY-MM-DD format
          min_amount: Minimum transaction amount
          max_amount: Maximum transaction amount
          category: Transaction category
          limit: Maximum number of results to return (default 100)
          no_invoice: Whether to exclude invoices
          no_receipt: Whether to exclude receipts
          status: Status of the transaction (UNVERIFIED, VERIFIED)
          cashflow_type: Cashflow type of the transaction (INCOME, EXPENSE)
          
      Returns:
          List of matching transactions with sensitive data removed
      """
      api = ctx.request_context.lifespan_context["api"]
      company_id = api.company_id
      
      if not company_id:
          return {"error": "No company available. Please authenticate first."}
      
      transactions_url = urljoin(
          config.api_base_url, 
          f"api/v1/companies/{company_id}/accounting/transactions/"
      )
      
      # Build query parameters
      params = {}
      if description:
          params["description"] = description
      if from_date:
          params["dateFrom"] = from_date
      if to_date:
          params["dateTo"] = to_date
      if min_amount:
          params["minAmount"] = min_amount
      if max_amount:
          params["maxAmount"] = max_amount
      if category:
          params["category_name"] = category
      if no_invoice:
          params["noInvoice"] = no_invoice
      if no_receipt:
          params["noAttachment"] = no_receipt
      if status:
          params["status"] = status
      if cashflow_type:
          params["cashflowType"] = cashflow_type
      if limit:
          params["limit"] = limit
      
      return api._make_request("GET", transactions_url, params=params)

• norman_mcp/server.py:327-336 (registration)

  The registration section in the MCP server setup where register_transaction_tools(server) is called. This invokes the registration of the search_transactions tool (and other transaction tools) with the FastMCP server instance.

  # Register all tools
  register_client_tools(server)
  register_invoice_tools(server)
  register_tax_tools(server)
  register_transaction_tools(server)
  register_document_tools(server)
  register_company_tools(server)
  register_prompts(server)
  register_resources(server)

• norman_mcp/server.py:19-19 (registration)

  Import of register_transaction_tools function from transactions.py, necessary for registering the tool.

  from norman_mcp.tools.transactions import register_transaction_tools