Skip to content
Back to search

local-mcp-toolkit

Три локальных MCP-сервера на Python: файлы, запуск скриптов и делегирование задач LLM. stdio, без портов и демонов.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vakatr--local-mcp-toolkit/badge.svg)](/listings/vakatr--local-mcp-toolkit)

HTML

<a href="/listings/vakatr--local-mcp-toolkit"><img src="/api/listings/vakatr--local-mcp-toolkit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/Vakatr/local-mcp-toolkit.git
cd local-mcp-toolkit
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -e .

For development:

pip install -e ".[dev]"

This installs three console scripts: `mcp-filesystem`, `mcp-python-runner`, `mcp-delegate`. Each can also be started as a module, for example `python -m local_mcp_toolkit.filesystem`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 229 lines
  1. # local-mcp-toolkit
  2. [![CI](https://github.com/Vakatr/local-mcp-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/Vakatr/local-mcp-toolkit/actions/workflows/ci.yml)
  3. Three local-first [Model Context Protocol](https://modelcontextprotocol.io/) servers in
  4. one Python package:
  5. - **filesystem** — encoding-aware text reads, directory listing, content search,
  6. metadata and writes.
  7. - **python-runner** — runs local Python scripts and analyzes their output.
  8. - **delegate** — forwards self-contained tasks to an OpenAI-compatible
  9. `/chat/completions` endpoint.
  10. All servers use the MCP stdio transport: they start as child processes of the MCP
  11. client, do not bind network ports, and need no daemon.
  12. ```mermaid
  13. flowchart LR
  14. Client[MCP client] -->|stdio| FS[filesystem]
  15. Client -->|stdio| PY[python-runner]
  16. Client -->|stdio| DEL[delegate]
  17. DEL -->|HTTP(S)| LLM[OpenAI-compatible endpoint]
  18. ```
  19. ## Requirements
  20. - Python 3.10 or newer
  21. - An MCP client (Claude Desktop, LM Studio, or any client that supports stdio servers)
  22. ## Install
  23. ```bash
  24. git clone https://github.com/Vakatr/local-mcp-toolkit.git
  25. cd local-mcp-toolkit
  26. python -m venv .venv
  27. # Windows
  28. .venv\Scripts\activate
  29. # macOS / Linux
  30. source .venv/bin/activate
  31. pip install -e .
  32. ```
  33. For development:
  34. ```bash
  35. pip install -e ".[dev]"
  36. ```
  37. This installs three console scripts: `mcp-filesystem`, `mcp-python-runner`,
  38. `mcp-delegate`. Each can also be started as a module, for example
  39. `python -m local_mcp_toolkit.filesystem`.
  40. ## Tools
  41. | Server | Tool | Purpose |
  42. |---|---|---|
  43. | filesystem | `read_text_file` | Read text, auto-detect utf-8 / cp1251 / utf-16 / latin-1 |
  44. | filesystem | `list_directory` | List entries, optionally recursive with a glob |
  45. | filesystem | `search_in_files` | Regex search across file contents |
  46. | filesystem | `file_info` | Size, line count, encoding, SHA-256 prefix |
  47. | filesystem | `write_text_file` | Write text, optionally creating parent directories |
  48. | python-runner | `run_python_script` | Run a `.py` file, capture stdout/stderr |
  49. | python-runner | `analyze_output` | Count lines, timestamps and regex hits |
  50. | python-runner | `run_and_analyze` | Run a script and analyze both output streams |
  51. | python-runner | `list_python_files` | Find `.py` files, skipping caches and virtualenvs |
  52. | delegate | `delegate` | Send a task to an OpenAI-compatible chat endpoint |
  53. | delegate | `list_models` | Query `GET /models` on the endpoint |
  54. | delegate | `health_check` | Check endpoint reachability and latency |
  55. ### filesystem
  56. Every path is expanded and resolved before use. When a root is configured, the
  57. resolved path must be relative to it; `..` traversal and symlinks that leave the
  58. root are rejected. Read and write roots are independent.
  59. | Variable | Effect |
  60. |---|---|
  61. | `MCP_FS_READ_ROOT` | Restrict reads, listing, search and `file_info` to this tree |
  62. | `MCP_FS_ROOT` | Restrict `write_text_file` to this tree |
  63. If a variable is unset, the corresponding operation is unrestricted.
  64. Hard limits:
  65. | Operation | Limit |
  66. |---|---|
  67. | `read_text_file` content | 10 MiB (`max_bytes` may request less) |
  68. | `write_text_file` encoded content | 2 MiB |
  69. | `list_directory` entries | 5000 |
  70. | `search_in_files` hits | 1000 |
  71. | `search_in_files` per-file scan | 10 MiB |
  72. `read_text_file` checks for a BOM first, then strict UTF-8, then a UTF-16
  73. byte-lane heuristic, then cp1251, and finally latin-1. Encoding detection is a
  74. heuristic: ambiguous single-byte files can be decoded as cp1251 rather than
  75. latin-1. Pass `encoding` to force a specific codec.
  76. `list_directory` and `search_in_files` skip common cache and vendor directories
  77. (`.git`, `.venv`, `venv`, `__pycache__`, `node_modules`, `build`, `dist`,
  78. `.mypy_cache`, `.pytest_cache`, `.ruff_cache`).
  79. `file_info` hashes the complete file but counts lines only in the first 10 MiB;
  80. `lines_truncated` reports when the count is partial. Files larger than 10 MiB
  81. are skipped by `search_in_files`.
  82. ### python-runner
  83. | Variable | Default | Effect |
  84. |---|---|---|
  85. | `MCP_RUNNER_ROOT` | unset | Restrict the script, working directory and listings to this tree |
  86. | `MCP_RUNNER_MAX_TIMEOUT` | `300` | Upper bound in seconds for a per-call `timeout` |
  87. | `MCP_RUNNER_INHERIT_SECRETS` | `0` | Set to `1` to pass secret-looking env vars to the child (not recommended) |
  88. `run_python_script` uses `subprocess.run` with an argument list and
  89. `shell=False`. The child inherits the parent environment, but variables whose
  90. names look like secrets (`*_KEY`, `*_TOKEN`, `*_SECRET`, `*_PASSWORD`,
  91. `*_CREDENTIALS`) are removed by default. `PYTHONIOENCODING=utf-8` is forced and
  92. `PYTHONUNBUFFERED=1` is set when absent. Only the first 50 000 characters of
  93. stdout and 20 000 of stderr are returned; truncated output ends with
  94. `... [truncated]`.
  95. `analyze_output` recognizes `DD.MM.YYYY HH:MM:SS` and ISO-like
  96. `YYYY-MM-DD HH:MM:SS` timestamps. The default patterns are `ERROR`, `WARN`,
  97. `Exception`, `Traceback`, `FAIL` and `[OK]`, matched case-insensitively. Invalid
  98. regexes are reported with a count of `-1` and listed in `invalid_patterns`.
  99. ### delegate
  100. The endpoint must implement the OpenAI chat-completions shape. All settings are
  101. optional.
  102. | Variable | Default | Description |
  103. |---|---|---|
  104. | `DELEGATE_BASE_URL` | `http://localhost:1234/v1` | Base URL, without a trailing `/chat/completions` |
  105. | `DELEGATE_API_KEY` | empty | Sent as `Authorization: Bearer ...` when set |
  106. | `DELEGATE_DEFAULT_MODEL` | `sub-agent` | Model used when the call omits one |
  107. | `DELEGATE_TIMEOUT` | `120` | Default HTTP timeout in seconds |
  108. | `DELEGATE_MAX_PROMPT` | `20000` | Maximum `task` length in characters |
  109. | `DELEGATE_MAX_RESPONSE` | `50000` | Maximum returned content length in characters |
  110. Input validation:
  111. - `task` must be a non-empty string no longer than `DELEGATE_MAX_PROMPT`.
  112. - `model` must be a non-empty string of at most 200 characters.
  113. - `max_tokens` is clamped to `1..8192`; `temperature` to `0.0..2.0`.
  114. - `timeout` is clamped to `1..600` seconds and defaults to `DELEGATE_TIMEOUT`.
  115. Responses longer than `DELEGATE_MAX_RESPONSE` are truncated and flagged with
  116. `"truncated": true`. HTTP, URL, timeout and JSON errors are returned as
  117. `{"ok": false, "error": ...}` dictionaries. HTTP redirects are refused so the
  118. `Authorization` header is never forwarded to another host, and proxy
  119. environment variables are ignored. The API key is placed only in the request
  120. header, is redacted if an endpoint reflects it in an error body, and never
  121. appears in results.
  122. ## Client configuration
  123. Ready-to-copy files:
  124. - [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json)
  125. - [`examples/lm_studio_config.json`](examples/lm_studio_config.json)
  126. Claude Desktop stores its configuration at:
  127. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  128. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  129. LM Studio reads MCP servers from its `mcp.json` configuration. The format is the
  130. same `mcpServers` object shown in the example.
  131. Minimal entry:
  132. ```json
  133. {
  134. "mcpServers": {
  135. "filesystem": {
  136. "command": "mcp-filesystem",
  137. "env": {
  138. "MCP_FS_READ_ROOT": "C:/Users/you/Documents",
  139. "MCP_FS_ROOT": "C:/Users/you/Documents/agent-workspace"
  140. }
  141. }
  142. }
  143. }
  144. ```
  145. If the client does not inherit your shell `PATH`, use the absolute path to the
  146. console script (for example
  147. `C:/Users/you/local-mcp-toolkit/.venv/Scripts/mcp-filesystem.exe` on Windows) or
  148. `command: "python"` with `args: ["-m", "local_mcp_toolkit.filesystem"]`.
  149. ## Security model
  150. - **python-runner executes arbitrary local code without a sandbox.** It has the
  151. same file and network access as the user running the MCP server.
  152. `MCP_RUNNER_ROOT` is a path guard for cooperative use, not a containment
  153. boundary against malicious scripts. Secret-looking environment variables are
  154. stripped from the child by default, but a script can still read files or open
  155. a network connection.
  156. - **filesystem roots are path checks, not an OS sandbox.** They prevent
  157. accidental reads/writes outside a tree. Any process that can run code as your
  158. user can bypass them.
  159. - **delegate sends tasks to the configured endpoint.** Use a local endpoint or
  160. HTTPS. A plain `http://` URL exposes the task and the API key to the network.
  161. The key is never logged by this package, but the endpoint necessarily
  162. receives it.
  163. - Only connect these servers to agents you trust. See [SECURITY.md](SECURITY.md)
  164. for the full threat model.
  165. ## Tests
  166. ```bash
  167. ruff check .
  168. pytest --cov=local_mcp_toolkit --cov-branch --cov-fail-under=85
  169. ```
  170. The suite uses temporary directories and fake HTTP transports; it does not
  171. need network access or a running MCP server. CI runs the same commands on
  172. Ubuntu and Windows with Python 3.11 and 3.13.
  173. ## Contributing
  174. See [CONTRIBUTING.md](CONTRIBUTING.md).
  175. ## License
  176. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.