Content
# local-tools MCP server
A minimal MCP server that exposes filesystem tools scoped to a single
"workspace" folder (`~/mcp-workspace` by default), plus the ability to
run Python scripts inside it.
Tools included:
**Filesystem**
- `list_dir` — list files/folders
- `tree` — recursive directory listing
- `read_file` — read a text file
- `write_file` — write/create a text file
- `append_file` — append to a file
- `delete_file` — delete a file
- `copy_file` — copy a file
- `move_file` — move/rename a file or folder
- `make_dir` — create a directory
- `delete_dir` — delete a directory (optionally recursive)
- `file_info` — size/timestamps/type metadata
- `search_files` — find files by glob pattern (e.g. `*.py`)
- `grep_files` — search file contents for a substring
- `file_hash` — sha256/sha1/md5 of a file
- `zip_dir` / `unzip_file` — zip and unzip archives
**Scripts / shell**
- `run_python_script` — run a `.py` file, capture stdout/stderr
- `run_shell_command` — run any shell command (cwd = workspace root)
**Git** (operates on the workspace root as a repo)
- `git_status`, `git_diff`, `git_log`, `git_add_commit`
**System / utility**
- `system_info` — OS, Python version, workspace path
- `list_env_vars` — environment variables (optional prefix filter)
- `current_time` — current local date/time
Filesystem tools are sandboxed to the workspace root so they can't
wander outside it. `run_shell_command` and `run_python_script` are
**not** sandboxed beyond their working directory — a shell command can
still do anything your user account can do, so only run this server on
a machine/account you're comfortable with, and review commands before
trusting them in automated flows.
## 1. Install dependencies
```bash
cd mcp-local-tools
python3 -m venv .venv
source .venv/bin/activate # on Windows: .venv\Scripts\activate
pip install -r requirements.txt
```
## 2. Test it standalone (optional)
```bash
mcp dev server.py
```
This opens the MCP Inspector in your browser so you can call the tools manually.
## 3. Connect it to Claude Desktop
Edit your Claude Desktop config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
Add:
```json
{
"mcpServers": {
"local-tools": {
"command": "/absolute/path/to/mcp-local-tools/.venv/bin/python",
"args": ["/absolute/path/to/mcp-local-tools/server.py"]
}
}
}
```
Restart Claude Desktop. The tools should appear under the 🔌 icon.
## 4. Connect it to Claude Code
```bash
claude mcp add local-tools -- /absolute/path/to/mcp-local-tools/.venv/bin/python /absolute/path/to/mcp-local-tools/server.py
```
## Customizing
- Change `ALLOWED_ROOT` in `server.py` to point at a different folder.
- Add new tools by writing a function decorated with `@mcp.tool()` —
the docstring becomes the tool description the model sees, and
type hints define the expected arguments.
