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`.
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
withInstances parameter:withInstances=true: Returns service details with instances (ServiceDetailInfo objects). withInstances=false: Returns service metadata without instances (ServiceView objects). **NOTE: ** When withInstances=true, The API may cost too much memory and networks, If Only want get instance list with little or one service, Suggest use withInstances=false with List 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 is public if 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.
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 is public if missing.groupName(string, optional): The groupName pattern of services, default is DEFAULT_GROUP if 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 is public if missing.groupName(string, optional): The groupName pattern of services, default is DEFAULT_GROUP if 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 is public if missing.groupName(string, optional): The groupName pattern of services, default is DEFAULT_GROUP if 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 is public if 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 is blur, optional value accurate.
- 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 is public if 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 is public if 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 is public if 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, id field.
- 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 is public if 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 is public if 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 `uvx` executable in the `command` field. You can get this by running `which uvx` on MacOS/Linux or `where uvx` on 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_nacos to 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.
[
{
"description": "Retrieves the list of namespaces in the current Nacos cluster.",
"inputSchema": {
"properties": {},
"type": "object"
},
"name": "list_namespaces"
},
{
"description": "This interface retrieves the list of services under a specified namespace. The response format depends on the `withInstances` parameter:`withInstances=true`: Returns service details with instances (`ServiceDetailInfo` objects). `withInstances=false`: Returns service metadata without instances (`ServiceView` objects). **NOTE: ** When `withInstances=true`, The API may cost too much memory and networks, If Only want get instance list with little or one service, Suggest use `withInstances=false` with `List Service Instances`.",
"inputSchema": {
"properties": {
"groupNameParam": {
"description": "The groupName pattern of services, default null means all group if missing. if not null, server will search all service match groupName both prefix and subfix, such as: input `test`, groupName `test`, `atest`, `testb`, `atestb` will all matched",
"type": "string"
},
"ignoreEmptyService": {
"description": "Whether ignore the empty service in result, default is true",
"type": "bool"
},
"namespaceId": {
"description": "The namespaceId of services, default is `public` if missing",
"type": "string"
},
"pageNo": {
"description": "The current page number, default is 1.",
"type": "int"
},
"pageSize": {
"description": "The size of services in each page, default is 100",
"type": "int"
},
"serviceNameParam": {
"description": "The serviceName pattern of services, default null means all service if missing. if not null, server will search all service match serviceName both prefix and subfix, such as: input `test`, serviceName `test`, `atest`, `testb`, `atestb` will all matched",
"type": "string"
},
"withInstances": {
"description": "Whether contain instances under each services in result, recommend and default is false",
"type": "bool"
}
},
"required": [
"pageNo",
"pageSize"
],
"type": "object"
},
"name": "list_services"
},
{
"description": "This interface retrieves detailed information of a specified service, including metadata and clusters, not including instance list.",
"inputSchema": {
"properties": {
"groupName": {
"description": "The groupName pattern of services, default is `DEFAULT_GROUP` if missing",
"type": "string"
},
"namespaceId": {
"description": "The namespaceId of services, default is `public` if missing",
"type": "string"
},
"serviceName": {
"description": "The serviceName pattern of services, required.",
"type": "string"
}
},
"required": [
"serviceName"
],
"type": "object"
},
"name": "get_service"
},
{
"description": "This interface retrieves the list of instances for a specified service.",
"inputSchema": {
"properties": {
"clusterName": {
"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`",
"type": "string"
},
"groupName": {
"description": "The groupName pattern of service, default is `DEFAULT_GROUP` if missing",
"type": "string"
},
"namespaceId": {
"description": "The namespaceId of service, default is `public` if missing",
"type": "string"
},
"serviceName": {
"description": "The serviceName pattern of service, required.",
"type": "string"
}
},
"required": [
"serviceName"
],
"type": "object"
},
"name": "list_service_instances"
},
{
"description": "This interface retrieves the list of subscribers for a specified service.",
"inputSchema": {
"properties": {
"aggregation": {
"description": "Whether aggregation from whole cluster, if `false`, only get subscribers from requested node, default `true` if missing",
"type": "bool"
},
"groupName": {
"description": "The groupName pattern of service, default is `DEFAULT_GROUP` if missing",
"type": "string"
},
"namespaceId": {
"description": "The namespaceId of service, default is `public` if missing",
"type": "string"
},
"pageNo": {
"description": "The current page number, default is 1.",
"type": "int"
},
"pageSize": {
"description": "The size of subscribers in each page, default is 100",
"type": "int"
},
"serviceName": {
"description": "The serviceName pattern of service, required.",
"type": "string"
}
},
"required": [
"pageNo",
"pageSize",
"serviceName"
],
"type": "object"
},
"name": "list_service_subscribers"
},
{
"description": "This interface retrieves the list of configurations under a specified namespace.",
"inputSchema": {
"properties": {
"appName": {
"description": "The appName of configs, default null means all appName, if not null, server will search all config match appName.",
"type": "string"
},
"configTags": {
"description": "The tags of configs, default null means all tags, if not null, server will search all config match tags. Multiple tags using `,` to split, such as `tag1,tag2`",
"type": "string"
},
"dataId": {
"description": "The dataId pattern of configs, default null means all dataId. if not null, server will search all config match dataId. If `search=blur`, this parameter allow use `*` to do blur search, such as `*test` to do prefix and `test*` to do suffix",
"type": "string"
},
"groupName": {
"description": "The groupName pattern of configs, default null means all group. if not null, server will search all config match groupName. If `search=blur`, this parameter allow use `*` to do blur search, such as `*test` to do prefix and `test*` to do suffix",
"type": "string"
},
"namespaceId": {
"description": "The namespaceId of configs, default is `public` if missing",
"type": "string"
},
"pageNo": {
"description": "The current page number, default is 1.",
"type": "int"
},
"pageSize": {
"description": "The size of configs in each page, default is 100",
"type": "int"
},
"search": {
"description": "The search way of list configs, default is `blur` means blur search groupName and dataId. Or using `accurate` means accurate match with groupName and dataId.",
"type": "string"
},
"type": {
"description": "The type of configs, default null means all type, if not null, server will search all config match type. Multiple type using `,` to split, such as `text,json`",
"type": "string"
}
},
"required": [
"pageNo",
"pageSize"
],
"type": "object"
},
"name": "list_configs"
},
{
"description": "This interface retrieves the details of the specified configuration.",
"inputSchema": {
"properties": {
"dataId": {
"description": "The dataId of config, Required.",
"type": "string"
},
"groupName": {
"description": "The groupName of config, Required.",
"type": "string"
},
"namespaceId": {
"description": "The namespaceId of configs, default is `public` if missing",
"type": "string"
}
},
"required": [
"groupName",
"dataId"
],
"type": "object"
},
"name": "get_config"
},
{
"description": "This interface retrieves the complete publish history of a configuration.",
"inputSchema": {
"properties": {
"dataId": {
"description": "The dataId pattern of config, required.",
"type": "string"
},
"groupName": {
"description": "The groupName pattern of config, required.",
"type": "string"
},
"namespaceId": {
"description": "The namespaceId of config, default is `public` if missing",
"type": "string"
},
"pageNo": {
"description": "The current page number, default is 1.",
"type": "int"
},
"pageSize": {
"description": "The size of config history records in each page, default is 100",
"type": "int"
}
},
"required": [
"pageNo",
"pageSize",
"groupName",
"dataId"
],
"type": "object"
},
"name": "list_config_history"
},
{
"description": "This interface retrieves a specific historical change record of a configuration.",
"inputSchema": {
"properties": {
"dataId": {
"description": "The dataId of config, Required.",
"type": "string"
},
"groupName": {
"description": "The groupName of config, Required.",
"type": "string"
},
"namespaceId": {
"description": "The namespaceId of configs, default is `public` if missing",
"type": "string"
},
"nid": {
"description": "the actual id of config history record, Get from list config history api/tool, `id` field.",
"type": "long"
}
},
"required": [
"groupName",
"dataId"
],
"type": "object"
},
"name": "get_config_history"
},
{
"description": "This interface retrieves the list of listeners subscribed to a specific configuration.",
"inputSchema": {
"properties": {
"aggregation": {
"description": "Whether aggregation from whole cluster, if `false`, only get listeners from requested node, default `true` if missing",
"type": "bool"
},
"dataId": {
"description": "The dataId of config, Required.",
"type": "string"
},
"groupName": {
"description": "The groupName of config, Required.",
"type": "string"
},
"namespaceId": {
"description": "The namespaceId of configs, default is `public` if missing",
"type": "string"
}
},
"required": [
"groupName",
"dataId"
],
"type": "object"
},
"name": "list_config_listeners"
},
{
"description": "This interface lists the configurations subscribed to by a specific client IP address.",
"inputSchema": {
"properties": {
"aggregation": {
"description": "Whether aggregation from whole cluster, if `false`, only get listeners from requested node, default `true` if missing",
"type": "bool"
},
"ip": {
"description": "The client ip of config listeners, Required.",
"type": "string"
},
"namespaceId": {
"description": "The namespaceId of configs, default is `public` if missing",
"type": "string"
}
},
"required": [
"ip"
],
"type": "object"
},
"name": "list_listened_configs"
}
]