# 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

```bash
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](docs/getting-started.md)).

See [docs/getting-started.md](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](docs/platforms/linux.md). |
| Windows | **Beta / unvalidated** | Implemented but never run on a real Windows host. See [docs/platforms/windows.md](docs/platforms/windows.md). |
| macOS | Implemented | See [docs/platforms/macos.md](docs/platforms/macos.md). |

## Documentation

- [Getting started](docs/getting-started.md) — install, configure, run as a service, connect an agent
- [Usage & tools](docs/usage.md) — the tool catalog and how to call it
- [Architecture](docs/architecture.md) — how the server is put together
- [Security model](docs/security.md) — the full permissions and threat model
- [Changelog](CHANGELOG.md) — 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](docs/security.md) for the full model.

## License

MIT — see [LICENSE](LICENSE).