Norman Finance MCP Server

Instructions

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