Combined MCP Server

A self-hosted MCP (Model Context Protocol) server that gives AI agents controlled access to a machine: filesystem, shell, background processes, git, web fetching and persistent key-value memory. Works over SSE (HTTP) or stdio.

Tools

Filesystem

Shell & processes

Git

All git tools accept a repository directory (path/cwd) and default to the server working directory. Arguments are passed to git without a shell, so commit messages and paths cannot inject commands.

Web & memory

Related MCP server: mcp-devtools

Quick start

npm install
node index.js            # SSE on http://localhost:8000/sse
PORT=9000 node index.js  # custom port
USE_STDIO=true node index.js  # stdio transport instead of HTTP

Security

Authentication (fail-closed)

Token auth for the HTTP endpoints turns on automatically as soon as at least one active token exists in tokens.json. MCP_REQUIRE_AUTH=1 forces auth on even with no tokens (rejects everything); MCP_REQUIRE_AUTH=0 disables auth explicitly:

# create tokens (any number, with TTL or forever)
node scripts/token.js create --name laptop --ttl 30d
node scripts/token.js create --name ci --count 5 --ttl 12h
node scripts/token.js create --name main            # never expires

node scripts/token.js list
node scripts/token.js revoke laptop                 # by name or by token value

node index.js   # auth is now enforced because active tokens exist

Clients pass the token as Authorization: Bearer <token> or ?token=<token> in the SSE URL (many SSE clients cannot set headers). Tokens live in tokens.json (chmod 600; override with MCP_TOKENS_FILE). The file is re-read on every request, so revocation takes effect immediately without a restart.

Path allowlist (opt-in)

Restrict filesystem and git tools to specific directories:

MCP_ALLOWED_DIRS="/home/user/projects:/tmp" node index.js

When unset, file tools can access everything the server user can (a warning is logged).

Known limitations

• executeShell and startProcess are not sandboxed: a shell command can touch anything the server user can, regardless of MCP_ALLOWED_DIRS. Disable or firewall them if you expose the server beyond localhost.

• The allowlist does not resolve symlinks pointing outside allowed directories.

• Prefer binding behind a reverse proxy with TLS when exposing the server to a network.

Configuration

Tests

node test/smoke.mjs   # token manager + live auth checks

CI runs syntax checks and the smoke test on every push/tag (.woodpecker.yml, Codeberg Woodpecker).

NixOS

nix develop      # shell with nodejs + git
npm install
nix run .#server # or just: node index.js