RadiusStack MCP Server
# RadiusStack MCP Server
A stdio [Model Context Protocol](https://modelcontextprotocol.io/) server for safe, targeted RadiusStack operations.
## Tools
| Tool | RadiusStack permission | Purpose |
|---|---|---|
| `radiusstack_get_live_stats` | reports read-only | Current live statistics |
| `radiusstack_list_users` | users read-only | Paginated users, with passwords redacted |
| `radiusstack_get_user_stats` | users read-only | Usage/authentication statistics for one user |
| `radiusstack_create_user` | users read-write | Create one RADIUS user |
| `radiusstack_update_user` | users read-write | Change selected user properties, including disabled state |
The server deliberately does **not** proxy arbitrary API routes, return user passwords, manage API keys, control HA, restart containers, operate certificates, or delete users.
## Install and configure
> The scoped npm package will be available after the first release is published. Until then, install from a checked-out repository with `npm install` and use the `node` command below.
Create a dedicated RadiusStack API administrator/key with only the permissions required by the tools you plan to use. For read-only monitoring, grant `reports: read-only` and `users: read-only`. For user creation/updates, additionally grant `users: read-write`. Do not use a platform administrator key.
### Claude Desktop
Add this to your Claude Desktop MCP configuration:
```json
{
"mcpServers": {
"radiusstack": {
"command": "npx",
"args": ["-y", "@radiusstack/mcp-server"],
"env": {
"RADIUSSTACK_URL": "https://radius.example.com",
"RADIUSSTACK_API_KEY": "replace-with-dedicated-least-privilege-key"
}
}
}
}
```
### Other MCP clients
Run `npx -y @radiusstack/mcp-server` as a stdio MCP server, setting `RADIUSSTACK_URL` and `RADIUSSTACK_API_KEY` in the client environment. `RADIUSSTACK_URL` must be an `http` or `https` URL; use HTTPS outside a trusted LAN.
## Development
```bash
npm install
npm test
RADIUSSTACK_URL=https://radius.example.com RADIUSSTACK_API_KEY=... npm start
```
## Publishing
1. Create the public GitHub repository `deangoldhill/radiusstack-mcp-server` and push this directory.
2. Create the public npm organization/scope `@radiusstack` (or change `name` in `package.json` to an available unscoped package name).
3. Authenticate with the npm account that owns the scope: `npm login`.
4. From a clean release checkout, run `npm test && npm publish --access public`.
5. Create and push a signed tag such as `v0.1.0`. The included GitHub Action can publish later tagged releases when an `NPM_TOKEN` repository secret is configured.
6. Confirm installation from a clean machine: `npx -y @radiusstack/mcp-server --help`.
Use semantic versioning. Publish only from a clean, reviewed commit; package contents can be checked before upload with `npm pack --dry-run`.
## Security notes
- API keys are supplied only through environment variables and are never logged or returned.
- `radiusstack_list_users` strips the RadiusStack API's password field before emitting tool output.
- The MCP tools are intentionally allowlisted and expose no generic request or command-execution capability.
- MCP clients should require user confirmation for mutations. The creation and update tools are marked as non-read-only.
## License
MIT
TDQS
Scored across 5 tools
Each tool has a distinct resource and action: live server stats, user listing, per-user stats, user creation, and user update. The two stats tools are clearly separated by scope (global live stats vs. single-user usage/auth stats).
All tools use the same radiusstack_ prefix followed by a clear verb_noun pattern. The naming is predictable and consistent across the entire surface.
Five tools are well within the ideal range for a focused RADIUS user-management server. Each tool maps to a meaningful operation and there is no obvious bloat.
The set covers listing, creating, updating, and reading stats for users, but lacks user deletion and a direct get-user/profile operation. These are notable lifecycle gaps for a user-management domain and may force workarounds.