mcp-node-server

MCP server exposing machine resources to remote AI agents over HTTP.

Why

AI agents (Hermes, Claude Desktop, Cursor, etc.) can connect to MCP servers to use external tools. But existing MCP servers for filesystem and terminal access are stdio-only — they must run on the same machine as the client, right next to it.

This project fills that gap: a single MCP server you install on your machine, exposing its resources (files, terminal, camera, screen, input) over HTTP. Any AI agent anywhere on your network — or over a VPN — can then reach those resources as first-class tools, without being co-located with them.

Quickstart

pip install -e .
mkdir -p ~/.config/mcp-node-server
cp config.example.yaml ~/.config/mcp-node-server/config.yaml   # then set auth_token, allowed_dirs
mcp-node-server start --transport http                          # HTTP for remote agents

The server binds to loopback (127.0.0.1) by default; to accept remote agents, set server.host / --host (see docs/getting-started.md).

See docs/getting-started.md for install options, per-OS setup, running as a service, and connecting an agent.

Platform support

Platform	Status	Notes
Linux	Validated	Primary target, full test suite green. See docs/platforms/linux.md.
Windows	Beta / unvalidated	Implemented but never run on a real Windows host. See docs/platforms/windows.md.
macOS	Implemented	See docs/platforms/macos.md.

Documentation

• Getting started — install, configure, run as a service, connect an agent
• Usage & tools — the tool catalog and how to call it
• Architecture — how the server is put together
• Security model — the full permissions and threat model
• Changelog — release history

Security

The MCP server is the security boundary — the agent connecting to it is untrusted. Filesystem whitelists, terminal command controls, opt-in device access, and bearer-token auth on HTTP all enforce that boundary; run the server VPN-only. See docs/security.md for the full model.

License

MIT — see LICENSE.