gremlin_mcp

Learning from this Youtube TUT https://www.youtube.com/watch?v=io02ZM0ADqM MCP Full Course for Beginners Note: I asked Copilot or some other LLM to clean up the existing code for tools and added any others it thought would be useful. There are several tools that should be used with caution as they can modify the files and directories. I haven't tested tool usage properly. Need to build something useful with this mcp and with proper guardrails.

An MCP (Model Context Protocol) server that gives an agent terminal and file-management capabilities: run shell/Python commands, search and read files, and create/edit/delete files and folders.

Built on FastMCP.

Tools

The server exposes 21 tools, grouped as follows:

Shell / Python execution

Tool	Purpose
run_command	Run a shell command (cmd on Windows, sh on Unix)
python_code	Execute a Python snippet with the running interpreter
python_file	Execute a Python script file

Search & read

Tool	Purpose
glob_files	List absolute paths matching a glob pattern
grep	Matching lines (with line numbers) in a single file
search_text	Recursive search under a directory
read_file	Read a whole file as UTF-8
read_file_lines	Read a 1-based range of lines
get_env_var	Read an environment variable

Files & folders

Tool	Purpose
write_file / append_file	Write or append UTF-8 text
replace_in_file	Find & replace, returns the count changed
copy_file / move_file	Copy or move (auto-creates parent dirs)
delete_file / delete_folder	Delete a file or folder
create_folder	Create a folder (including parents)
list_dir / get_cwd / file_info / tree	Directory introspection

Requirements

• Python >= 3.13
• fastmcp >= 3.4.7

Installation

uv sync            # recommended
# or
python -m pip install -e .

Starting the server

The server communicates over stdio, which is FastMCP's default transport. Start it from the repo root with any of:

uv run python -m gremlin_mcp.main
python test.py serve
python start_gremlin_mcp_server.py

Testing

1. Offline smoke test (no MCP client needed)

python test.py

This imports the server, calls every tool (creating and cleaning up a temporary folder), and prints a [PASS]/[FAIL] summary plus a total.

2. Interactive web inspector

fastmcp dev inspector src/gremlin_mcp/main.py

Opens the MCP Inspector in your browser so you can browse the tools, read their descriptions/examples, and call them interactively.

Note: fastmcp dev is a subcommand group, so the inspector subcommand must be passed explicitly (fastmcp dev src/... alone will fail).

3. Quick CLI checks

fastmcp inspect src/gremlin_mcp/main.py    # server info + tool summary
fastmcp list   src/gremlin_mcp/main.py     # just the tool names

4. Connecting from an MCP client

Point your editor/client's MCP config at the server via stdio, for example:

{
  "mcpServers": {
    "gremlin-mcp": {
      "command": "uv",
      "args": ["run", "python", "-m", "gremlin_mcp.main"]
    }
  }
}

Example tool calls

As an agent would issue them:

list_dir(path="src")
search_text(pattern="TODO", directory="src")
read_file(file="pyproject.toml")
write_file(file="hello.py", content="print('hi')")
python_code(code="print(6 * 7)")          # -> exit=0 / 42
replace_in_file(path="config.py", old="DEBUG = True", new="DEBUG = False")
tree(path=".", depth=2)

Project layout

src/gremlin_mcp/
├── __init__.py
├── tools.py   # all tool definitions (21 tools)
└── main.py    # FastMCP server entry point
test.py        # offline smoke test / optional server launcher
start_gremlin_mcp_server.py   # minimal "run the server" launcher

Security note

run_command, python_code and python_file execute arbitrary code. Only expose this server to agents/clients you trust, and consider running it inside a sandbox or restricted working directory.