Minimal Node.js MCP server

A small, stateless MCP server built with TypeScript, tsx, Zod, and the official Model Context Protocol SDK.

Run

npm install
npm start

On Windows, running through npm.cmd can show Terminate batch job (Y/N)? after Ctrl+C. That prompt comes from the Windows batch wrapper, not this server. Once Server stopped safely. appears, active work has already finished and it is safe to answer Y. To avoid the batch prompt entirely, launch Node directly:

node --import tsx src/index.ts

The MCP endpoint is http://localhost:5555/mcp. A readable health endpoint is available at http://localhost:5555/health.

Choose another workspace or port:

npm start -- --cwd ./my-workspace --port 6000

--cwd is resolved from the project root/current launch directory. When omitted, the server creates:

sandbox/yymmdd-hhMMss

The timestamp is captured once, when the server process starts. For example: sandbox/260729-013045.

Related MCP server: MCP Server

Stateless behavior

This server intentionally uses stateless Streamable HTTP. It does not issue or require an Mcp-Session-Id; every MCP request can be handled independently. The configured workspace and its files still persist for the lifetime of the server process (and on disk afterward).

Each run_cmd call starts a new shell process in the configured workspace. Shell-local state such as cd, aliases, and environment variables does not carry over to later tool calls. To work in a subdirectory for one command, use a single command such as cd project && npm test.

Models should use ls, read_file, write_file, mkdir, and delete_file instead of shell commands whenever one of those tools matches the operation. This is especially important on Windows: a process started by run_cmd can keep a file open, and Windows will not allow either the filesystem tool or a shell command to delete that file until the owning process exits.

Use with llama.cpp WebUI

Current llama.cpp WebUI releases support MCP over Streamable HTTP. This server allows browser CORS requests from every origin, including preflight and Chromium private-network requests, so it can be connected directly or through llama-server's built-in MCP proxy.

1. Start this MCP server:

   npm start

2. Either connect the WebUI directly, or start llama-server with its MCP proxy:

   llama-server [your usual model options] --ui-mcp-proxy

3. In the llama.cpp WebUI MCP settings, add:

   • URL: http://127.0.0.1:5555/mcp

   • Transport: Streamable HTTP

   • Use llama-server proxy: optional

--webui-mcp-proxy is the deprecated name of the llama.cpp option; prefer --ui-mcp-proxy. The WebUI may keep a live MCP connection and reconnect it, but this server remains stateless and does not depend on transport-session continuity.

Press Ctrl+C once to stop accepting new connections and wait for active MCP requests (including file writes and commands) to finish. Press Ctrl+C a second time only when you intentionally want to force the process to stop.

Included tools

• Filesystem: ls, read_file, write_file, mkdir, delete_file

• Command: run_cmd

• Computation: js_calculator

• Real world: get_current_time

There is intentionally no command sandbox or path restriction.

js_calculator accepts JavaScript expressions as well as multiple statements. Separate statements with semicolons; the final expression supplies the returned value. For example, const x = pow(2, 10); x + log(E) returns 1025. Wrap a final object literal in parentheses, such as const x = 2; ({ x, square: x*x }). It is intended for calculations, not as a general Node.js runner; Node.js process, require, filesystem, and network APIs are not provided.

Add a tool

Create or edit a module under src/tools, then add its exported array to src/tools/index.ts:

{
  name: "echo",
  description: "Return the supplied text.",
  inputSchema: {
    text: z.string(),
  },
  handler: ({ text }) => ({ text }),
}

The registry handles MCP registration, Zod validation, result serialization, and error conversion.