Climatiq MCP Server

Instructions

Implementation Reference

• src/climatiq_mcp_server/tools.py:682-740 (handler)

  Main handler function for the 'travel-spend' tool. Validates inputs, constructs request to Climatiq API endpoint '/travel/v1-preview1/spend', processes response, generates summary text, and handles caching.

  async def travel_spend_tool(config, arguments, server, climatiq_request):
      """
      Calculate carbon emissions from travel-related spending.
      
      This tool uses a spend-based method to estimate emissions from various travel activities:
      - Air travel spending
      - Road travel spending (including taxis)
      - Rail travel spending
      - Sea travel spending
      - Hotel accommodation spending
      
      The calculation uses economic input-output models to estimate the carbon intensity
      of different travel services based on financial spend data.
      """
      spend_type = arguments.get("spend_type")
      money = arguments.get("money")
      money_unit = arguments.get("money_unit")
      spend_location = arguments.get("spend_location")
      spend_year = arguments.get("spend_year")
      
      if not spend_type or not money or not money_unit or not spend_location:
          raise ValueError("Missing required parameters for travel spend calculation")
          
      # Validate spend type
      valid_spend_types = ["air", "road", "rail", "sea", "hotel"]
      if spend_type.lower() not in valid_spend_types:
          raise ValueError(f"Invalid spend_type: {spend_type}. Must be one of: {', '.join(valid_spend_types)}")
          
      # Construct the request to the Climatiq API
      request_data = {
          "spend_type": spend_type.lower(),
          "money": money,
          "money_unit": money_unit,
          "spend_location": spend_location
      }
      
      if spend_year:
          request_data["spend_year"] = spend_year
          
      try:
          result = await climatiq_request("/travel/v1-preview1/spend", request_data)
          
          # Store in cache
          cache_id = f"travel_spend_{spend_type}_{money}_{money_unit}_{id(result)}"
          
          co2e = result.get("co2e", 0)
          co2e_unit = result.get("co2e_unit", "kg")
          location_name = result.get("spend_location", {}).get("name", "unknown location")
          
          spend_type_display = spend_type.capitalize()
          result_text = f"{spend_type_display} travel spending of {money} {money_unit} in {location_name} "
          result_text += f"results in {co2e} {co2e_unit} of CO2e emissions."
          result_text += f"\n\nDetailed results are available as a resource with ID: {cache_id}"
          
          return result_text, result, cache_id
          
      except ValueError as e:
          error_text = f"Error calculating travel spend emissions: {str(e)}"
          return error_text, None, None

• src/climatiq_mcp_server/tools.py:877-891 (schema)

  Schema definition for the 'travel-spend' tool, including input schema, description, and parameters.

  types.Tool(
      name="travel-spend",
      description="Calculate carbon emissions from travel-related spending based on spend type, amount, currency, location, and year.",
      inputSchema={
          "type": "object",
          "properties": {
              "spend_type": {"type": "string", "description": "Type of travel spending (air, road, rail, sea, hotel)"},
              "money": {"type": "number", "description": "Amount of money spent"},
              "money_unit": {"type": "string", "description": "Currency unit for the spent money"},
              "spend_location": {"type": "string", "description": "Location of the travel spending"},
              "spend_year": {"type": "number", "description": "Year of the travel spending"},
          },
          "required": ["spend_type", "money", "money_unit", "spend_location"],
      },
  )

• src/climatiq_mcp_server/server.py:224-229 (registration)

  MCP server registration of tools via list_tools handler, which returns all tool definitions including 'travel-spend' from get_tool_definitions() in tools.py.

  @server.list_tools()
  async def handle_list_tools() -> list[types.Tool]:
      """
      List available tools for interacting with the Climatiq API.
      """
      return get_tool_definitions()

• src/climatiq_mcp_server/server.py:264-265 (registration)

  Dispatch logic in the generic call_tool handler that routes 'travel-spend' calls to the travel_spend_tool function.

  elif name == "travel-spend":
      result_text, result, cache_id = await travel_spend_tool(config, arguments, server, climatiq_request)

• src/climatiq_mcp_server/server.py:32-44 (helper)

  Import of the travel_spend_tool handler and get_tool_definitions for tool registration from tools.py.

  from climatiq_mcp_server.tools import (
      set_api_key_tool,
      electricity_emission_tool,
      travel_emission_tool,
      search_emission_factors_tool,
      custom_emission_calculation_tool,
      cloud_computing_emission_tool,
      freight_emission_tool,
      procurement_emission_tool,
      hotel_emission_tool,
      travel_spend_tool,
      get_tool_definitions
  )