Getting Started

Overview

The SimpleNS MCP Server implements the Model Context Protocol, allowing AI assistants like Claude Desktop, Cursor, and others to interact with your SimpleNS instance to send notifications, check analytics, and manage alerts.

Supported Transports:

Streamable HTTP — Local usage via npm package
Stdio — Local usage via command line / npm package

No installation is required when using npx.

Credentials Required

To connect, clients need to provide the following headers or environment variables. The server is stateless and verifies these on every request.

Header Name	Environment Variable (Stdio)	Description
`X-SimpleNS-API-Key`	`NS_API_KEY`	Your SimpleNS secure API Key
`X-SimpleNS-Core-URL`	`SIMPLENS_CORE_URL`	Public URL of the core engine (api)
`X-SimpleNS-Dashboard-URL`	`SIMPLENS_DASHBOARD_URL`	Public URL of the dashboard

Connection Configurations

Copy the appropriate configuration for your tool.

Streamable HTTP

Start the server locally with npx -y @simplens/mcp (defaults to port 3001), then add this to your settings.json:

{
    "servers": {
        "simplens": {
            "type": "streamable-http",
            "url": "http://localhost:3001/mcp",
            "headers": {
                "X-SimpleNS-API-Key": "your-ns-api-key",
                "X-SimpleNS-Core-URL": "http://localhost:3000",
                "X-SimpleNS-Dashboard-URL": "http://localhost:3002"
            }
        }
    },
    "inputs": []
}

Stdio

Add this to your settings.json:

{
    "servers": {
        "simplens": {
            "command": "npx",
            "args": ["-y", "@simplens/mcp", "--stdio"],
            "env": {
                "NS_API_KEY": "your-local-api-key",
                "SIMPLENS_CORE_URL": "http://localhost:3000",
                "SIMPLENS_DASHBOARD_URL": "http://localhost:3002"
            }
        }
    },
    "inputs": []
}

Streamable HTTP

Start the server locally with npx -y @simplens/mcp (defaults to port 3001), then add this to your mcp_config.json:

{
    "mcpServers": {
        "simplens": {
            "serverUrl": "http://localhost:3001/mcp",
            "headers": {
                "X-SimpleNS-API-Key": "your-ns-api-key",
                "X-SimpleNS-Core-URL": "http://localhost:3000",
                "X-SimpleNS-Dashboard-URL": "http://localhost:3002"
            }
        }
    }
}

Stdio

Add this to your mcp_config.json:

{
    "mcpServers": {
        "simplens": {
            "command": "npx",
            "args": ["-y", "@simplens/mcp", "--stdio"],
            "env": {
                "NS_API_KEY": "your-local-api-key",
                "SIMPLENS_CORE_URL": "http://localhost:3000",
                "SIMPLENS_DASHBOARD_URL": "http://localhost:3002"
            }
        }
    }
}

Streamable HTTP

Start the server locally with npx -y @simplens/mcp (defaults to port 3001), then add this to your config.toml:

[mcp_servers.simplens]
url = "http://localhost:3001/mcp"
http_headers = { "X-SimpleNS-API-Key" = "your-ns-api-key", "X-SimpleNS-Core-URL" = "http://localhost:3000", "X-SimpleNS-Dashboard-URL" = "http://localhost:3002" }

Stdio

Add this to your config.toml:

[mcp_servers.simplens]
command = "npx"
args = ["-y", "@simplens/mcp", "--stdio"]

[mcp_servers.simplens.env]
NS_API_KEY = "your-local-api-key"
SIMPLENS_CORE_URL = "http://localhost:3000"
SIMPLENS_DASHBOARD_URL = "http://localhost:3002"

Getting Started

On this page