web-tools-mcp-server (mcptools)

An all-in-one MCP server for local LLMs (Gemma, gpt-oss, Qwen, etc. via LM Studio, Ollama, or any MCP client). It gives a model the capabilities small local models lack: live web access, precise math, the current date, shell + code execution, filesystem and SQLite access, a persistent memory, and semantic search (RAG) over your own files using LM Studio embeddings.

• Transport: stdio (local).

• Config: ~/.config/mcptools/config.json (auto-created on first run).

• No cloud keys required — search is Startpage (+ Google headless fallback), weather is open-meteo, embeddings are your local LM Studio.

• 39 tools in 10 config-gated groups.

Table of contents

• Tools

• Tool reference

• Install & build

• Run

• Register with a client — Claude Code · OpenCode · Generic

• Configuration

• RAG / LM Studio

• Development

Related MCP server: MCP Server

Tools (39, in 10 groups)

⚠️ Security: run_command, execute_code, write_file, edit_file, download_file and unrestricted filesystem access run with your user's full privileges (only timeouts, no sandbox — as configured). Run this server only with clients/models you trust, or disable those groups in the config (see Configuration).

Tool reference

Every tool returns human-readable text plus structuredContent for programmatic clients. Responses are capped to limits.characterLimit and truncated with a note.

web

compute

system

files

data

knowledge

feeds

memory

tasks

rag

Install & build

cd ~/Code/mcptools
npm install
npm run build      # compiles to dist/

Requires Node ≥ 22 (uses the built-in node:sqlite). python3 is needed for execute_code with language: "python".

Run

node dist/index.js     # speaks MCP over stdio

The first run writes a default ~/.config/mcptools/config.json.

Register with a client

Install script (recommended)

npm run install:claude     # Claude Code (~/.claude.json, user scope)
npm run install:opencode   # OpenCode (~/.config/opencode/opencode.json)
npm run install:all        # both

Merges the mcptools entry into the client's user-level config (everything else in the file is preserved; re-running updates the entry in place). Build first — the script points the client at dist/index.js.

Claude Code (manual)

claude mcp add mcptools -- node ./dist/index.js

OpenCode

Add to ~/.config/opencode/config.json (global) or a project opencode.json, under the mcp key:

{
  "mcp": {
    "mcptools": {
      "type": "local",
      "command": ["node", "./dist/index.js"],
      "enabled": true
    }
  }
}

Restart OpenCode (or start a new session) to spawn the server. Verify with /mcp inside OpenCode, or list tools from the TUI.

Generic MCP client (mcpServers JSON)

{
  "mcpServers": {
    "mcptools": {
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

💡 Small local models choose tools more reliably with fewer of them. If 39 tools is too many for your model, disable groups in the config rather than the client — see below.

Configuration (~/.config/mcptools/config.json)

{
  "groups": {                 // turn whole tool groups on/off
    "web": true, "compute": true, "system": true, "data": true,
    "knowledge": true, "memory": true, "rag": true
  },
  "tools": {                  // per-tool overrides win over group, e.g.:
    // "run_command": false,
    // "write_file": false
  },
  "limits": {
    "timeoutMs": 30000,       // network/exec timeout
    "characterLimit": 25000,  // max chars per tool response
    "maxOutputBytes": 1000000 // max bytes captured from a process/file/fetch
  },
  "lmstudio": {
    "baseUrl": "http://localhost:1234/v1",
    "embeddingModel": "text-embedding-nomic-embed-text-v1.5"
  },
  "paths": { "dataDir": "~/.config/mcptools" }
}

• Per-tool overrides (tools) take precedence over the group switch.

• Hot env overrides: MCPTOOLS_LMSTUDIO_URL, MCPTOOLS_EMBED_MODEL.

• For a safe, read-only-ish profile set "system": false (and optionally "data": false) in groups.

A copy of the defaults lives in config.example.json.

RAG / embedding server

rag_index and rag_search call any OpenAI-compatible /v1/embeddings endpoint. At startup, the server auto-detects which embedding backend is running and uses it:

1. The URL in lmstudio.baseUrl (or MCPTOOLS_LMSTUDIO_URL env var) — primary.

2. http://localhost:1234/v1 — LM Studio.

3. http://localhost:8089/v1 — highllama / llama.cpp.

For each, it hits /v1/models with a 2 s timeout, picks the most promising embedding model (configured id, then anything with embed/bge/minilm/e5 in its id), and verifies with a real probe /v1/embeddings call that the model actually returns a numeric vector. This rejects llama.cpp servers that are currently serving a chat model (the common case — llama.cpp loads one model at a time, so if it's busy with gemma-4-26B for chat, it can't also serve embeddings). For single-model servers with a name that doesn't match the patterns, the same probe is used as a fallback so custom-named embedding models are still discovered. The chosen endpoint is logged to stderr on startup, e.g.:

[mcptools/rag] using LM Studio (1234) with model "text-embedding-nomic-embed-text-v1.5"

If nothing is reachable, the configured values are used and the embedding call will fail with a clear error.

⚠️ Embedding model crashing on GPU — load it on CPU

Observed with text-embedding-nomic-embed-text-v1.5: the model crashes mid-request ("The model has crashed... Exit code: null") and then fails to reload ("unable to allocate CUDA0 buffer"). Root cause is GPU/CUDA, not the input — the same chunks embed fine on CPU. This tiny (~84 MB) model runs fast on CPU.

Load it CPU-only (the lms CLI is the only place that sets the GPU layer-offload ratio — the REST API does not):

~/.lmstudio/bin/lms unload --all
~/.lmstudio/bin/lms load text-embedding-nomic-embed-text-v1.5 --gpu off -y

Loads in ~0.5 s and embeds reliably. An explicitly-loaded model has no TTL and stays resident until LM Studio restarts, so JIT won't reload it on the GPU.

Persisting it (headless / no GUI). The GUI "per-model default" is the correct knob and applies to JIT loading, but LM Studio only writes it from the GUI (into an undocumented internal file — don't hand-edit it). Headless options:

• Run the lms load ... --gpu off command at login (e.g. a systemd --user oneshot unit, or append it to your existing ~/.lmstudio/load-optimized.sh).

• Or just run it once per LM Studio session before using RAG.

If you have the GUI on another machine: My Models → ⚙️ → set GPU offload = 0.

Defensive hardening (any backend)

• Inputs are embedded one at a time (batched array input crashes some backends).

• Each embed call retries with backoff.

• rag_index skips any chunk that still fails and reports the count, instead of aborting the whole index.

Development

npm run dev        # tsx watch (no build step)
npm run build      # type-check + compile
npm run clean      # remove dist/

Project layout:

src/
  index.ts            entry: load config, register enabled tools, stdio
  config.ts           config load/merge + defaults (~/.config/mcptools)
  registry.ts         group/tool enable gating
  types.ts            shared types
  services/           search (mojeek), lmstudio (embeddings), vectorstore
  tools/              web, compute, system, data, knowledge, memory, rag
  util/               http, html, exec, sqlite, format, errors

Data files created at runtime under paths.dataDir (default ~/.config/mcptools): config.json, memory.db, rag.db.