⚡ Published on PyPI and compatible with MCP clients that support the stdio transport.

Smart Terminal MCP

A lightweight Model Context Protocol (MCP) server built with FastMCP that lets AI assistants work with files, git and Python on your local machine, inside a protected workspace folder.

Giving an AI agent a raw terminal is risky: it could delete files, read secrets or run commands you never intended. This project explores how to expose useful local tools to MCP clients with safety nets built in.

✨ Features

• List, read, write and search files (glob, grep, read_file, write_file)

• Create and (softly) delete folders

• Run a small allowlist of safe commands: ls, pwd, echo and read-only git (status, log, diff, show)

• Run Python code and Python files (opt-in, off by default)

• Every file operation is confined to one workspace folder

• Works on Windows, macOS and Linux (developed and tested on Windows)

• One command to run: uvx smart_terminal_mcp

Related MCP server: local-mcp

🛡️ Security Model

⚠️ Important limitation

The folder jail protects the file, search and git tools. Python execution is not sandboxed: when enabled, Python code can access anything your user account can. Enable it only with agents you trust, or run the server inside Docker (on the roadmap).

📦 Installation

Using uv (Recommended)

Run it directly without installing:

uvx smart_terminal_mcp

Or add it to a project:

uv add smart_terminal_mcp

Using pip

pip install smart_terminal_mcp

🚀 MCP Server Configuration

You need an MCP client (Claude Desktop, Claude Code, Cursor, VS Code, Codex, or your own LangGraph app) and uv installed.

Claude Desktop / Cursor style

{
  "mcpServers": {
    "smart_terminal": {
      "command": "uvx",
      "args": ["smart_terminal_mcp"],
      "env": {
        "SMART_TERMINAL_ROOT": "C:\\Users\\me\\projects\\my-app"
      }
    }
  }
}

LangChain MCP adapters style

{
  "smart_terminal": {
    "transport": "stdio",
    "command": "uvx",
    "args": ["smart_terminal_mcp"],
    "env": {
      "SMART_TERMINAL_ROOT": "/path/to/workspace"
    }
  }
}

Claude Code

claude mcp add smart_terminal -- uvx smart_terminal_mcp

Settings (environment variables)

📂 Available Tools

🔄 How It Works

LLM  ⇄  MCP client (Claude, Cursor, ...)  ⇄  smart_terminal_mcp  ⇄  workspace folder
 (cloud)        (on your computer)        (started by uvx, stdio)     (your files and git)

1. Your MCP client starts the server with uvx smart_terminal_mcp.

2. The LLM asks the client to call a tool; the client forwards it over stdio.

3. The server validates the request (path jail, allowlist, limits) and only then runs it.

4. The result, or a Blocked/Error message, goes back to the LLM.

The server runs entirely on your own machine. Nothing is hosted.

🧪 Testing

uv run python test.py

Or open the MCP Inspector against the server:

npx @modelcontextprotocol/inspector uv run smart_terminal_mcp

Things worth trying: ls; whoami (blocked), reading ../anything (blocked), reading .env (blocked), writing to an existing file without overwrite=True (refused).

📁 Project Structure

smart_terminal_mcp/
│
├── src/
│   └── smart_terminal_mcp/
│       ├── main.py
│       └── tools.py
│
├── test.py
├── pyproject.toml
├── README.md
└── LICENSE

🎯 Motivation

The goal of this project was to gain hands-on experience with the Model Context Protocol (MCP) by building a practical server, and to learn why safety design matters when AI agents can touch a real machine.

It helped me understand:

• MCP architecture and the stdio transport

• Tool registration with FastMCP

• Path traversal and why paths must be resolved before checking

• Why raw shell=True is dangerous, and allowlisting as an alternative

• Python packaging and PyPI publishing

• Honest threat modelling: what a safeguard does and does not protect

🔮 Roadmap

• Docker mode for a true sandbox (including Python execution)

• delete_file, edit_file (partial edits), move and copy operations

• More read-only commands and richer ls options

• Git actions with explicit approval (add, commit)

• Tool execution audit log

• More testing on macOS and Linux

⚠️ Disclaimer

This project is intended for educational and development purposes. Even with the safety nets above, only connect it to agents and clients you trust, and point SMART_TERMINAL_ROOT at a dedicated project folder, never at your home directory or system folders.

📜 License

MIT License

👨‍💻 Author

Mohd Bilal

If you found this project interesting, feel free to star the repository.