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

Search & read

Files & folders

Related MCP server: emcp

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.