MCP Nautobot Server

Instructions

Implementation Reference

• src/mcp_nautobot_server/server.py:633-659 (handler)

  The MCP tool handler in handle_call_tool that extracts the ip_id argument, calls the NautobotClient's get_ip_address_by_id method, handles not found cases, and returns a formatted text response with JSON data.

  elif name == "get_ip_address_by_id":
      ip_id = args.get("ip_id")
      if not ip_id:
          raise ValueError("ip_id is required")
      
      logger.info(f"Retrieving IP address by ID: {ip_id}")
      
      # Get specific IP address
      ip_address = await client.get_ip_address_by_id(ip_id)
      
      if ip_address is None:
          return [
              types.TextContent(
                  type="text",
                  text=f"IP address with ID '{ip_id}' not found in Nautobot."
              )
          ]
      
      result = ip_address.model_dump()
      
      return [
          types.TextContent(
              type="text",
              text=f"Retrieved IP address from Nautobot:\n\n"
                   f"```json\n{result}\n```"
          )
      ]

• src/mcp_nautobot_server/server.py:481-495 (registration)

  Registration of the 'get_ip_address_by_id' tool in list_tools, including name, description, and input schema requiring 'ip_id'.

  types.Tool(
      name="get_ip_address_by_id",
      description="Retrieve a specific IP address by its Nautobot ID",
      inputSchema={
          "type": "object",
          "properties": {
              "ip_id": {
                  "type": "string",
                  "description": "The Nautobot ID of the IP address"
              }
          },
          "required": ["ip_id"],
          "additionalProperties": False
      },
  ),

• src/mcp_nautobot_server/nautobot_client.py:47-66 (schema)

  Pydantic model defining the structure of IPAddress data returned by the tool.

  class IPAddress(BaseModel):
      """Pydantic model for Nautobot IP address data."""
      
      id: str
      url: HttpUrl
      address: str
      status: Dict[str, Any]
      role: Optional[Dict[str, Any]] = None
      tenant: Optional[Dict[str, Any]] = None
      vrf: Optional[Dict[str, Any]] = None
      nat_inside: Optional[Dict[str, Any]] = None
      nat_outside: Optional[Dict[str, Any]] = None
      dns_name: Optional[str] = None
      description: Optional[str] = None
      comments: Optional[str] = None
      tags: List[Dict[str, Any]] = Field(default_factory=list)
      custom_fields: Dict[str, Any] = Field(default_factory=dict)
      created: str
      last_updated: str

• src/mcp_nautobot_server/nautobot_client.py:390-410 (helper)

  Core helper method in NautobotClient that performs the API GET request to retrieve IP address by ID, parses to IPAddress model, and returns None on 404.

  async def get_ip_address_by_id(self, ip_id: str) -> Optional[IPAddress]:
      """
      Retrieve a specific IP address by its ID.
      
      Args:
          ip_id: The IP address ID
          
      Returns:
          IPAddress object or None if not found
          
      Raises:
          NautobotError: For API or connection errors
      """
      try:
          response = await self._make_request("GET", f"/ipam/ip-addresses/{ip_id}/")
          return IPAddress(**response)
      except NautobotAPIError as e:
          if e.status_code == 404:
              return None
          raise