list_service_instances

Retrieve service instances from Nacos by specifying service name, namespace, group, and cluster parameters to discover available endpoints.

Instructions

This interface retrieves the list of instances for a specified service.

Input Schema

TableJSON Schema

Name	Required	Description
`namespaceId`	No	The namespaceId of service, default is `public` if missing
`groupName`	No	The groupName pattern of service, default is `DEFAULT_GROUP` if missing
`serviceName`	Yes	The serviceName pattern of service, required.
`clusterName`	No	The cluster name of instances in service, optional and default is null means match all cluster. If need match multiple cluster, use `,` to split like `cluster1,cluster2`

Implementation Reference

src/mcp_server_nacos/server.py:104-107 (handler)
Specific handler case for the 'list_service_instances' tool within the MCP server's call_tool function. It retrieves the API URL from the tool class and executes an HTTP GET request via NacosServer.get to list service instances.
```
case nacos_tools.NacosToolNames.LIST_INSTANCES:
    url = nacos_tools.NacosListInstances().url
    result = nacos.get(name, url, arguments)
    return [types.TextContent(type="text", text=result)]
```

src/mcp_server_nacos/nacos_tools.py:71-92 (schema)

Tool class defining the schema, input validation, description, and Nacos API endpoint for 'list_service_instances'.

class NacosListInstances(NacosTool):
    def __init__(self):
        super().__init__(
            name=NacosToolNames.LIST_INSTANCES,
            description="This interface retrieves the list of instances for a specified service.",
            inputSchema={
                "type": "object",
                "properties": {
                    "namespaceId": {"type": "string",
                                    "description": "The namespaceId of service, default is `public` if missing"},
                    "groupName": {"type": "string",
                                  "description": "The groupName pattern of service, default is `DEFAULT_GROUP` if missing"},
                    "serviceName": {"type": "string",
                                    "description": "The serviceName pattern of service, required."},
                    "clusterName": {"type": "string",
                                    "description": "The cluster name of instances in service, optional and default is null means match all cluster. If need match multiple cluster, use `,` to split like `cluster1,cluster2`"},
                },
                "required": ["serviceName"],
            },
            url="/nacos/v3/admin/ns/instance/list"
        )

src/mcp_server_nacos/server.py:71-86 (registration)

Registration of all tools, including NacosListInstances (line 78), in the MCP server's list_tools decorator function.

@server.list_tools()
async def handle_list_tools() -> list[types.Tool]:
    """List available tools"""
    return [
        nacos_tools.NacosListNamespacesTool(),
        nacos_tools.NacosListServices(),
        nacos_tools.NacosGetService(),
        nacos_tools.NacosListInstances(),
        nacos_tools.NacosListServiceSubscribers(),
        nacos_tools.NacosListConfigs(),
        nacos_tools.NacosGetConfig(),
        nacos_tools.NacosListConfigHistory(),
        nacos_tools.NacosGetConfigHistory(),
        nacos_tools.NacosListConfigListeners(),
        nacos_tools.NacosListListenedConfigs(),
    ]

src/mcp_server_nacos/server.py:37-46 (helper)

NacosServer.get method, which performs the actual HTTP GET request to Nacos API, used by all tool handlers including list_service_instances.

def get(self, name:str, url: str, params: Any = None) -> str:
    url = f'http://{self.host}:{self.port}{url}'
    logger.debug(f'GET {url} with params {params}')
    result = self._request(url, params=params)
    if result is None:
        return "Unexpected error: None result handled."
    if result.is_success():
        return str(result.data)
    return f'Do {name} failed with message: {result.message}'

src/mcp_server_nacos/nacos_tools.py:261-273 (helper)

Enum defining the tool name constant 'list_service_instances' used in schema, handler, and registration.

class NacosToolNames(str, Enum):
    LIST_NAMESPACES = "list_namespaces",
    LIST_SERVICES = "list_services",
    GET_SERVICE = "get_service",
    LIST_INSTANCES = "list_service_instances",
    LIST_SERVICE_SUBSCRIBERS = "list_service_subscribers",
    LIST_CONFIGS = "list_configs",
    GET_CONFIG = "get_config",
    LIST_CONFIG_HISTORY = "list_config_history",
    GET_CONFIG_HISTORY = "get_config_history",
    LIST_CONFIG_LISTENERS = "list_config_listeners",
    LIST_LISTENED_CONFIGS = "list_listened_configs",

Nacos MCP Server