search_ip_addresses

Search IP addresses in Nautobot by querying IP addresses, descriptions, or other network data to retrieve infrastructure information.

Instructions

Search IP addresses using a general query string

Input Schema

TableJSON Schema

Name	Required	Description	Default
`query`	Yes	Search query (can match IP address, description, etc.)
`limit`	No	Maximum number of results to return (default: 50, max: 500)

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

MCP Nautobot Server