Skip to main content
Glama

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

Related MCP server: SSH MCP Server

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.

Available Tools

21 tools
append_fileB

Append text to a file, creating it first if needed.

Inputs: path (required), content (required). Returns: result

copy_fileC

Copy a file to a new location.

Inputs: dst (required), src (required). Returns: result

create_folderA

Create a folder, including parent folders if needed.

Inputs: folder (required). Returns: result

delete_fileA

Delete a single file.

Inputs: path (required). Returns: result

delete_folderB

Recursively delete a folder.

Inputs: folder (required). Returns: result

file_infoA

Return metadata about a file or folder (type, size, modified time).

Inputs: path (required). Returns: result

get_cwdA

Return the current working directory of the server process.

Example: get_cwd()

Inputs: no named parameters. Returns: result

get_env_varB

Return the value of an environment variable.

Inputs: name (required). Returns: result

glob_filesA

Return file paths matching a glob pattern (recursive).

Inputs: pattern (required). Returns: result

grepA

Return lines matching pattern in a single file, with line numbers.

Inputs: file (required), pattern (required). Returns: result

list_dirA

List the contents of a directory (name and type, sorted).

Inputs: path. Returns: result

move_fileC

Move or rename a file or folder.

Inputs: dst (required), src (required). Returns: result

python_codeB

Execute a Python snippet with the running interpreter.

Inputs: code (required). Returns: result

python_fileC

Execute a Python script file with the running interpreter.

Inputs: file (required). Returns: result

read_fileA

Read a file's contents as UTF-8 text.

Inputs: file (required). Returns: result

read_file_linesA

Read a range of lines (1-based, inclusive) from a file.

Out-of-range numbers are clamped to the file's actual length.

Inputs: end (required), path (required), start (required). Returns: result

replace_in_fileC

Replace all occurrences of old with new in a file.

Inputs: new (required), old (required), path (required). Returns: result

run_commandA

Execute a shell command and return its output.

The command runs through the platform shell (cmd on Windows, sh on Unix), so pipes, redirects and chained commands work. Use with care: this tool can run arbitrary commands.

Inputs: command (required). Returns: result

search_textA

Recursively search files under directory for pattern.

Common build/venv/cache directories are skipped automatically.

Inputs: pattern (required), directory. Returns: result

treeB

Show a tree of the directory structure up to a given depth.

Inputs: path, depth. Returns: result

write_fileA

Write UTF-8 content to a file (created if missing, overwritten if present).

Inputs: file (required), content (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 21 tools

    Disambiguation4/5

    Most tools have distinct purposes (file ops, command execution, code execution, search). However, `read_file` and `read_file_lines` overlap in reading file content, and `grep` vs `search_text` both search for patterns, though one is single-file and the other recursive. Minor confusion possible.

    Naming Consistency4/5

    Tool names follow a consistent verb_noun pattern (e.g., `read_file`, `delete_file`, `create_folder`). Some deviations like `glob_files` and `grep` break the pattern slightly, but overall it's clear and predictable.

    Tool Count5/5

    With 21 tools, the server covers a comprehensive set of file system operations, command execution, and code running. Each tool serves a specific need, and the count is well-suited for a general-purpose utility server without being excessive.

    Completeness5/5

    The tool set provides full file lifecycle (create, read, write, append, replace, move, copy, delete) plus directory management, search (glob, grep, text search), environment variable access, and code execution. No obvious gaps for the stated purpose of a file system and command execution MCP server.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server providing filesystem operations, shell execution, and web search capabilities.
      21 PyPI
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that gives AI agents SSH capabilities to execute commands, transfer files, and inspect remote systems through a preconfigured host list.
      93 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that lets you execute commands, manage files, run persistent shell sessions, transfer large files, and control background processes on remote machines via a lightweight HTTP agent, useful when SSH/WinRM/SMB are unavailable.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server exposing pi coding-agent tools for file and shell operations, including read, write, edit, bash, grep, find, and ls.
      1
      MIT