gremlin-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gremlin-mcp run ls -la to list files in the current directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 a shell command (cmd on Windows, sh on Unix) |
| Execute a Python snippet with the running interpreter |
| Execute a Python script file |
Search & read
Tool | Purpose |
| List absolute paths matching a glob pattern |
| Matching lines (with line numbers) in a single file |
| Recursive search under a directory |
| Read a whole file as UTF-8 |
| Read a 1-based range of lines |
| Read an environment variable |
Files & folders
Tool | Purpose |
| Write or append UTF-8 text |
| Find & replace, returns the count changed |
| Copy or move (auto-creates parent dirs) |
| Delete a file or folder |
| Create a folder (including parents) |
| 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.pyTesting
1. Offline smoke test (no MCP client needed)
python test.pyThis 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.pyOpens the MCP Inspector in your browser so you can browse the tools, read their descriptions/examples, and call them interactively.
Note:
fastmcp devis a subcommand group, so theinspectorsubcommand 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 names4. 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" launcherSecurity 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 toolsappend_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
Scored across 21 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for agentverse documentation, generated by doc2mcp.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
The MCP server for Azure DevOps, bringing the power of Azure DevOps directly to your agents.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server providing filesystem operations, shell execution, and web search capabilities.21 PyPI-
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI agents SSH capabilities to execute commands, transfer files, and inspect remote systems through a preconfigured host list.93 npmMIT
- AlicenseNot gradedqualityCmaintenanceAn 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
- AlicenseNot gradedqualityDmaintenanceMCP server exposing pi coding-agent tools for file and shell operations, including read, write, edit, bash, grep, find, and ls.1MIT