mcp-server-nacos: A Nacos MCP server
Overview
Nacos is an easy-to-use platform designed for dynamic service discovery and configuration and service management. It helps you to build cloud native applications and microservices platform easily.
This MCP(Model Context Protocol) Server is for Nacos interaction and automation. This server provides tools to search and read namespace, service and configuration relative information in Nacos Cluster via Large Language Models.
Please note that mcp-server-nacos is currently in early development. The functionality and available tools are subject to change and expansion as we continue to develop and improve the server. And also note that mcp-server-nacos only provide read, search and list operation, not support any write operation for current version. Write operation is planning supported in future versions.
One more note that this mcp-server-nacos required version:
1. Nacos version required upper `3.0.0`, because of depended on the [Nacos Admin API](https://nacos.io/en/swagger/admin/) in 3.x.
2. python version required 3.x, recommend upper `3.13`.
Tools
list_namespaces- Retrieves the list of namespaces in the current Nacos cluster.
- Input:
- None
- Returns: list of namespaces in the current Nacos cluster.
list_services- This tool retrieves the list of services under a specified namespace. The response format depends on the
withInstancesparameter:withInstances=true: Returns service details with instances (ServiceDetailInfoobjects).withInstances=false: Returns service metadata without instances (ServiceViewobjects). **NOTE: ** WhenwithInstances=true, The API may cost too much memory and networks, If Only want get instance list with little or one service, Suggest usewithInstances=falsewithList Service Instances. - Input:
pageNo(number): The current page number, default is 1.pageSize(number): The size of services in each page, default is 100.namespaceId(string, optional): The namespaceId of services, default ispublicif missing.groupNameParam(string, optional): The groupName pattern of services, default null means all group if missing.serviceNameParam(string, optional): The serviceName pattern of services, default null means all service if missing.ignoreEmptyService(bool, optional): Whether ignore the empty service in result, default is true.withInstances(bool, optional): Whether contain instances under each services in result, recommend and default is false.
- Returns: list of services under a specified namespace.
- This tool retrieves the list of services under a specified namespace. The response format depends on the
get_service- This tool retrieves detailed information of a specified service, including metadata and clusters, not including instance list.
- Input:
namespaceId(string, optional): The namespaceId of services, default ispublicif missing.groupName(string, optional): The groupName pattern of services, default isDEFAULT_GROUPif missing.serviceName(string): The serviceName pattern of services, required.
- Returns: detailed information of a specified service.
list_service_instances- This tool retrieves the list of instances for a specified service.
- Input:
namespaceId(string, optional): The namespaceId of services, default ispublicif missing.groupName(string, optional): The groupName pattern of services, default isDEFAULT_GROUPif missing.serviceName(string): The serviceName pattern of services, required.clusterName(string, optional): The cluster name of instances in service, optional and default is null means match all cluster.
- Returns: list of instances for a specified service.
list_service_subscribers- This tool retrieves the list of subscribers for a specified service.
- Input:
pageNo(number): The current page number, default is 1.pageSize(number): The size of service subscribers in each page, default is 100.namespaceId(string, optional): The namespaceId of services, default ispublicif missing.groupName(string, optional): The groupName pattern of services, default isDEFAULT_GROUPif missing.serviceName(string): The serviceName pattern of services, required.aggregation(bool, optional): Whether aggregation from whole cluster.
- Returns: list of subscribers for a specified service.
list_configs- This tool retrieves the list of configurations under a specified namespace.
- Input:
pageNo(number): The current page number, default is 1.pageSize(number): The size of configs in each page, default is 100.namespaceId(string, optional): The namespaceId of configs, default ispublicif missing.groupName(string, optional): The groupName pattern of configs, default null means all group.dataId(string, optional): The dataId pattern of configs, default null means all dataId.type(string, optional): The type of configs, default null means all type.configTags(string, optional): The tags of configs, default null means all tags.appName(string, optional): The appName of configs, default null means all appName.search(string, optional): The search way of list configs, default isblur, optional valueaccurate.
- Returns: list of configurations under a specified namespace.
get_config- retrieves the details of the specified configuration.
- Input:
namespaceId(string, optional): The namespaceId of configs, default ispublicif missing.groupName(string): The groupName of config, Required.dataId(string): The dataId of config, Required.
- Returns: the details of the specified configuration.
list_config_history- This tool retrieves the complete publish history of a configuration.
- Input:
pageNo(number): The current page number, default is 1.pageSize(number): The size of config history records in each page, default is 100.namespaceId(string, optional): The namespaceId of configs, default ispublicif missing.groupName(string): The groupName of config, Required.dataId(string): The dataId of config, Required.
- Returns: list of configurations under a specified namespace.
get_config_history- retrieves a specific historical change record of a configuration.
- Input:
namespaceId(string, optional): The namespaceId of configs, default ispublicif missing.groupName(string): The groupName of config, Required.dataId(string): The dataId of config, Required.nid(number): the actual id of config history record, Get from list config history tool,idfield.
- Returns: historical change record of a configuration.
list_config_listeners
- retrieves the list of listeners subscribed to a specific configuration.
- Input:
namespaceId(string, optional): The namespaceId of configs, default ispublicif missing.groupName(string): The groupName of config, Required.dataId(string): The dataId of config, Required.aggregation(bool, optional): Whether aggregation from whole cluster.
- Returns: list of listeners subscribed to a specific configuration.
list_listened_configs
- retrieves lists the configurations subscribed to by a specific client IP address.
- Input:
namespaceId(string, optional): The namespaceId of configs, default ispublicif missing.ip(string): The client ip of config listeners, Required.aggregation(bool, optional): Whether aggregation from whole cluster.
- Returns: lists the configurations subscribed to by a specific client IP address.
Installation
Using uv (recommended)
When using uv no specific installation is needed. We will
use uvx to directly run mcp-server-nacos.
Using PIP
Alternatively you can install mcp-server-nacos via pip:
pip install mcp-server-nacos
After installation, you can run it as a script using:
python -m mcp_server_nacos
Configuration
Usage with Claude Desktop
Add this to your claude_desktop_config.json:
Using uvx
"mcpServers": {
"git": {
"command": "uvx",
"args": [
"nacos-mcp-server",
"--host",
"your_nacos_host",
"--port",
"your_nacos_main_port, such as 8848",
"--access_token",
"your_nacos_access_token, get from `login` api: /nacos/v3/auth/user/login with `username` and `password`"
],
}
}
You may need to put the full path to the
uvxexecutable in thecommandfield. You can get this by runningwhich uvxon MacOS/Linux orwhere uvxon Windows.
Using pip installation
"mcpServers": {
"git": {
"command": "python",
"args": [
"-m",
"nacos-mcp-server",
"--host",
"your_nacos_host",
"--port",
"your_nacos_main_port, such as 8848",
"--access_token",
"your_nacos_access_token, get from `login` api: /nacos/v3/auth/user/login with `username` and `password`"
],
}
}
Development
If you are doing local development, simply follow the steps:
- Clone this repo into your local environment.
- Modify codes in
src/mcp_server_nacosto implement your wanted features. - Test using the Claude desktop app. Add the following to your claude_desktop_config.json:
{
"mcpServers": {
"mcp-server-nacos": {
"command": "uv",
"args": [
"--directory",
"/<path to mcp-server-nacos>/src/mcp_server_nacos",
"run",
"mcp-server-nacos"
]
}
}
License
mcp-server-nacos is licensed under the Apache 2.0 License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the Apache 2.0 License. For more details, please see the LICENSE file in the project repository.