Ugreen NAS Server

This repository contains a secure, containerized Model Context Protocol (MCP) server designed to be hosted on your Ugreen NAS (UGOS).

Security Architecture (Pre-Gateway Mitigations)

This setup is configured with several key pre-gateway security practices:

1. Transport Layer Token Authentication: Direct SSE access is protected with a token (X-API-Key header).
2. Container Isolation (Non-Root): The server runs as mcpuser (UID/GID 1000) inside the container. Even if a tool is compromised, the attacker has no root privileges and is restricted to the container environment.
3. Directory Sandboxing: The list_nas_shared_directories tool is restricted to /volume1/shared inside the container. It cannot traverse to other system files or directories on your NAS.
4. Environment-Driven Secrets: The secret token is passed via a Docker environment variable rather than hardcoded in the codebase.

---

Deployment on Ugreen NAS (UGOS)

Step 1: Build the Docker Image

You can build this image locally and push it to your NAS, or build it directly on the NAS if you have SSH enabled:

docker build -t ugreen-nas-mcp:latest .

Step 2: Running via Ugreen Container Manager UI

1. Open the App Center -> Container Manager (or Docker app) on your Ugreen NAS.
2. Go to Image and import/load ugreen-nas-mcp:latest or upload the folder and build it.
3. Create a new container with the image:
   • Network: Bridge (recommended, expose port 8000).
   • Port Settings: Map Container Port 8000 to Host Port 8000 (or another free port like 8080).
   • Environment Variables:
     • MCP_SECRET_TOKEN: Set a strong random password (e.g. uGr33n-S3cur3-Mcp-2026!).
   • Volume/Bind Mounts:
     • Mount the NAS shared directory you want the MCP to access (e.g. /volume1/homes or a specific shared folder /volume1/Public) to /volume1/shared inside the container. Set it to Read-Only (Recommended) for maximum security.
4. Start the container.

---

Client Configuration

To connect your AI client (e.g., Claude Desktop, Cursor, or another MCP client) to the NAS MCP server, update your client's configuration file:

Example: claude_desktop_config.json

Replace <NAS_IP> with the local IP address of your Ugreen NAS, and the header value with your configured MCP_SECRET_TOKEN.

{
  "mcpServers": {
    "ugreen-nas-mcp": {
      "type": "sse",
      "url": "http://<NAS_IP>:8000/mcp/sse",
      "headers": {
        "X-API-Key": "your-configured-mcp-secret-token"
      }
    }
  }
}

---

Verification & Testing

To verify the server is running and secure, run a quick curl command from your computer:

# Verify it blocks unauthorized access (Should return 401 Unauthorized)
curl -i http://<NAS_IP>:8000/mcp/sse

# Verify authorized access (Should establish connection)
curl -i -H "X-API-Key: your-configured-mcp-secret-token" http://<NAS_IP>:8000/mcp/sse