MCP Nautobot Server

Instructions

Implementation Reference

• src/mcp_nautobot_server/server.py:661-686 (handler)

  Specific handler logic within the shared handle_call_tool function for executing the search_ip_addresses tool: validates input parameters, calls the Nautobot client helper, formats the results as JSON, and returns a formatted text response.

  elif name == "search_ip_addresses":
      query = args.get("query")
      if not query:
          raise ValueError("query is required")
      
      limit = min(args.get("limit", 50), 500)  # Cap at 500 for search
      
      logger.info(f"Searching IP addresses with query: {query}")
      
      # Search IP addresses
      ip_addresses = await client.search_ip_addresses(query, limit)
      
      # Format results
      result = {
          "query": query,
          "count": len(ip_addresses),
          "results": [ip.model_dump() for ip in ip_addresses]
      }
      
      return [
          types.TextContent(
              type="text",
              text=f"Found {len(ip_addresses)} IP addresses matching '{query}':\n\n"
                   f"```json\n{result}\n```"
          )
      ]

• src/mcp_nautobot_server/server.py:499-516 (schema)

  Input schema defining parameters for the search_ip_addresses tool: requires 'query' string, optional 'limit' integer (default 50, 1-500).

  inputSchema={
      "type": "object",
      "properties": {
          "query": {
              "type": "string",
              "description": "Search query (can match IP address, description, etc.)"
          },
          "limit": {
              "type": "integer",
              "description": "Maximum number of results to return (default: 50, max: 500)",
              "default": 50,
              "minimum": 1,
              "maximum": 500
          }
      },
      "required": ["query"],
      "additionalProperties": False
  },

• src/mcp_nautobot_server/server.py:496-517 (registration)

  Registration of the search_ip_addresses tool in the @server.list_tools() handler, defining name, description, and input schema.

  types.Tool(
      name="search_ip_addresses",
      description="Search IP addresses using a general query string",
      inputSchema={
          "type": "object",
          "properties": {
              "query": {
                  "type": "string",
                  "description": "Search query (can match IP address, description, etc.)"
              },
              "limit": {
                  "type": "integer",
                  "description": "Maximum number of results to return (default: 50, max: 500)",
                  "default": 50,
                  "minimum": 1,
                  "maximum": 500
              }
          },
          "required": ["query"],
          "additionalProperties": False
      },
  ),

• src/mcp_nautobot_server/nautobot_client.py:411-447 (helper)

  NautobotClient helper method implementing the core search logic: sends GET request to /ipam/ip-addresses/ with q=query and limit params, parses response into IPAddress objects.

  async def search_ip_addresses(
      self, 
      query: str, 
      limit: int = 50
  ) -> List[IPAddress]:
      """
      Search IP addresses using a general query.
      
      Args:
          query: Search query (can be IP, description, etc.)
          limit: Maximum number of results
          
      Returns:
          List of matching IPAddress objects
      """
      params: Dict[str, Any] = {
          "q": query,
          "limit": limit,
      }
      
      try:
          response = await self._make_request("GET", "/ipam/ip-addresses/", params)
          
          ip_addresses = []
          for item in response.get("results", []):
              try:
                  ip_addresses.append(IPAddress(**item))
              except Exception as e:
                  logger.warning(f"Failed to parse IP address data: {e}")
                  continue
          
          logger.info(f"Found {len(ip_addresses)} IP addresses matching '{query}'")
          return ip_addresses
          
      except Exception as e:
          logger.error(f"Failed to search IP addresses: {e}")
          raise