Content
# Nacos MCP Server
Nacos configuration center's MCP (Model Context Protocol) Server, allowing AI assistants to directly read and search configuration information in Nacos. Built on top of [mcp-go](https://github.com/mark3labs/mcp-go) and [nacos-sdk-go](https://github.com/nacos-group/nacos-sdk-go), communicates with MCP clients via stdio, without listening to any network ports.
[](https://github.com/Vinkugor/nacos-mcp/releases)
[](LICENSE)
---
## Features
| Tool | Description | Status |
| ---- | ---- | ---- |
| `get_config` | Get specified configuration content by dataId and group | Available |
| `list_configs` | List configuration list under specified group (supports pagination) | Available |
| `search_config` | Fuzzy search configuration by keyword (dataId prefix match) | Available |
| `publish_config` | Publish/Add configuration to Nacos (supports `dryRun` preview) | Available (disabled in read-only mode) |
| `update_config` | Modify existing configuration (supports `dryRun` return current and new content comparison) | Available (disabled in read-only mode) |
---
## Quick Start
### Prerequisites
- Accessible Nacos Server (see [environment variables](#environment-variables) for specific version correspondence)
- Go developers need Go 1.23+ when using `go install`
### Installation
#### Method 1: npx (Recommended)
Add to MCP client configuration:
```json
{
"mcpServers": {
"nacos": {
"command": "npx",
"args": ["-y", "@vinkugor/nacos-mcp"],
"env": {
"NACOS_HOST": "localhost:8848",
"NACOS_NAMESPACE": "your-namespace",
"NACOS_USERNAME": "nacos",
"NACOS_PASSWORD": "nacos"
}
}
}
}
```
npx will automatically download the corresponding binary and cache it on the first run.
#### Method 2: go install (Go Developers)
```bash
go install github.com/Vinkugor/nacos-mcp@latest
```
Then, in the MCP client configuration, point `command` to the installed binary (ensure `$GOBIN` or `$GOPATH/bin` is in PATH):
```json
{
"mcpServers": {
"nacos": {
"command": "nacos-mcp",
"env": {
"NACOS_HOST": "localhost:8848",
"NACOS_NAMESPACE": "your-namespace",
"NACOS_USERNAME": "nacos",
"NACOS_PASSWORD": "nacos"
}
}
}
}
```
#### Method 3: Precompiled Binary (Offline / Intranet)
Download the corresponding platform's compressed package from [Releases](https://github.com/Vinkugor/nacos-mcp/releases), extract it, and point `command` to the absolute path of the binary:
```json
{
"mcpServers": {
"nacos": {
"command": "/usr/local/bin/nacos-mcp",
"env": {
"NACOS_HOST": "localhost:8848",
"NACOS_NAMESPACE": "your-namespace",
"NACOS_USERNAME": "nacos",
"NACOS_PASSWORD": "nacos"
}
}
}
}
```
---
## Environment Variables
### Required Configuration
| Variable | Description | Example |
| ---- | ---- | ---- |
| `NACOS_HOST` | Nacos server address | `localhost:8848` |
| `NACOS_USERNAME` | Login username | `nacos` |
| `NACOS_PASSWORD` | Login password | `nacos` |
### Optional Configuration
| Variable | Description | Default |
| ---- | ---- | ------ |
| `NACOS_NAMESPACE` | Namespace name or UUID (leave blank for public) | Empty |
| `NACOS_CONTEXT_PATH` | API path prefix (modify when custom deployment) | `/nacos` |
| `NACOS_SDK_VERSION` | SDK version (`v2` for Nacos Server v2/v3, `v1` for v1) | `v2` |
| `NACOS_READONLY` | Read-only mode (disable publish and modify functions when set to `true`) | `false` |
### Configuration Description
**Namespace Identification**
`NACOS_NAMESPACE` can be filled with the display name of the namespace (e.g., `dev-env`) or UUID (e.g., `cff9f83d-...`). The service will automatically convert the display name to UUID during startup, and output a warning if the conversion fails, but it will not affect the startup.
**Security Recommendation**
Please modify the default username and password in the production environment. Using the default credentials will output a security warning.
**Real-time Guarantee**
This service disables local snapshot caching, and all configuration reads are directly connected to the Nacos Server, ensuring that the latest configuration is obtained instead of stale cache.
---
## Makefile Commands
| Command | Description |
| ---- | ---- |
| `make build` | Compile current platform binary |
| `make build-all` | Compile all platform binaries (Linux/macOS/Windows) |
| `make run` | `go run .` start service |
| `make test` | Run tests |
| `make deps` | Download and organize dependencies |
| `make clean` | Clean build artifacts |
| `make install` | Compile and install to `/usr/local/bin/` |
---
## Technology Stack
| Component | Version |
| ---- | ---- |
| Go | 1.23+ |
| mcp-go | v0.7.0 |
| nacos-sdk-go (v2) | v2.3.5 |
| nacos-sdk-go (v1) | v1.1.6 |
## License
[Apache License 2.0](LICENSE)
