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

Tool	Description
readFile	Read a file
writeFile	Write a file (parent directories are created automatically)
editFile	Replace an exact string in a file; preserves file permissions, fails if the match is ambiguous
listDirectory	List directory contents
searchFiles	Grep-like regex search (pattern, path, optional include glob)
findFiles	Find files by glob pattern (src/**/*.js)

Shell & processes

Tool	Description
executeShell	Run a command via /bin/sh (60 s timeout, 10 MB output cap)
startProcess	Start a long-running background process (dev server, build)
processStatus	List background processes or inspect one
readProcessOutput	Read captured stdout+stderr (ring buffer, 200 KB per process)
stopProcess	Send a signal to a background process (default SIGTERM)

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.

Tool	Description
gitStatus	git status
gitDiff	git diff, optionally for one file
gitCommit	git add . && git commit -m <message>
gitLog	Recent commits, optionally for one path
gitBranch	List, create or switch branches
gitShow	Show a commit (message + diff, or --stat summary)

Web & memory

Tool	Description
fetchUrl	Fetch a URL and convert HTML to Markdown
storeValue / getValue	Persistent key-value memory (memory.json)

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

Env var	Default	Meaning
PORT	8000	HTTP port for SSE mode
USE_STDIO	unset	true = stdio transport instead of HTTP
MCP_REQUIRE_AUTH	auto	1 = force auth on, 0 = force off; unset = on when active tokens exist
MCP_TOKENS_FILE	./tokens.json	Token storage location
MCP_ALLOWED_DIRS	unset	Colon-separated allowlist for file/git tools

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