Norman Finance MCP Server

Instructions

Create a new client.

Args:
    name: Client name or business name
    client_type: Type of client (defaults to "business"), Options: "business", "private"
    address: Client physical address
    zip_code: Client postal/zip code
    email: Client email address
    country: Client country code (e.g. "DE")
    vat_number: Client VAT number
    city: Client city
    phone: Client phone number
    
Returns:
    Newly created client record

Implementation Reference

• norman_mcp/tools/clients.py:64-128 (handler)

  The handler function decorated with @mcp.tool() that implements the core logic for creating a new client by making a POST request to the Norman Finance API endpoint.

  @mcp.tool()
  async def create_client(
      ctx: Context,
      name: str,
      client_type: str = "business",
      address: Optional[str] = None,
      zip_code: Optional[str] = None,
      email: Optional[str] = None,
      country: Optional[str] = None,
      vat_number: Optional[str] = None,
      city: Optional[str] = None,
      phone: Optional[str] = None
  ) -> Dict[str, Any]:
      """
      Create a new client.
      
      Args:
          name: Client name or business name
          client_type: Type of client (defaults to "business"), Options: "business", "private"
          address: Client physical address
          zip_code: Client postal/zip code
          email: Client email address
          country: Client country code (e.g. "DE")
          vat_number: Client VAT number
          city: Client city
          phone: Client phone number
          
      Returns:
          Newly created client record
      """
      api = ctx.request_context.lifespan_context["api"]
      company_id = api.company_id
      
      if not company_id:
          return {"error": "No company available. Please authenticate first."}
      
      if client_type not in ["business", "private"]:
          return {"error": "client_type must be either 'business' or 'private'"}
      
      clients_url = urljoin(
          config.api_base_url, 
          f"api/v1/companies/{company_id}/clients/"
      )
      
      client_data = {
          "name": name,
          "clientType": client_type
      }
  
      if email:
          client_data["email"] = email
      if phone:
          client_data["phone"] = phone
      if vat_number:
          client_data["vatNumber"] = vat_number
      if address:
          client_data["address"] = address
      if zip_code:
          client_data["zipCode"] = zip_code
      if country:
          client_data["country"] = country
      if city:
          client_data["city"] = city
          
      return api._make_request("POST", clients_url, json_data=client_data)

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

  The registration block in the MCP server setup where register_client_tools(server) is called, which in turn registers the 'create_client' tool among other client tools.

  # 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)