<p align="center"> <img src="icon.jpg" alt="DevMCP" width="96" /> </p>

DevMCP

A single-file MCP server that turns any folder on your machine into a workspace an AI agent can work in: read and edit files, search code, run shell commands, manage background jobs, test HTTP endpoints, browse pages in headless Chromium, extract PDFs, and capture the screen.

It speaks streamable HTTP, so any remote MCP client can connect through an ngrok tunnel.

How it works

1. dev_server.py runs an MCP server on 127.0.0.1:8787. The folder it is launched from becomes the workspace root — file tools are sandboxed to it; shell tools are not.
2. ngrok exposes the port publicly so your MCP client can reach it.
3. The client calls the tools to read/edit files, run commands, and inspect images or screenshots.

Tools

Tool	Purpose
workspace_info	Project path plus system details: OS, architecture, shell, Python
project_overview	Manifests (package.json, pyproject.toml, ...) and README head
project_tree	Depth-limited directory tree
view_dir	Single-directory listing with sizes
list_files	Recursive file list (capped, junk dirs skipped)
read_file	Read a file slice with line numbers
file_outline	Class/function/export lines with line numbers
write_file	Create or overwrite a file (UTF-8)
edit_file	Exact-match single replacement
search_code	ripgrep search with a pure-Python fallback
run_cmd	Shell command in the project folder (blocking)
run_powershell	PowerShell in the project folder (blocking)
git	Git wrapper (status, diff, log, commit, ...)
start_process	Run a long command in the background, returns a job id
check_process	Job status plus the tail of its output
stop_process	Kill a background job's process tree
http_request	Test HTTP/API endpoints, including localhost
fetch_page	Load a URL in headless Chromium (JS-rendered text or HTML)
browser_screenshot	Screenshot of a URL rendered in headless Chromium
view_image	Send an image file from the project to the client
screenshot	Capture a monitor
read_pdf	Extract text from a PDF
view_pdf_page	Render one PDF page as an image
restart_server	Restart to pick up dev_server.py changes
stop_server	Shut down; the launcher cleans up ngrok

Requirements

• Python 3.11+
• ngrok (a free account with a reserved domain is recommended)
• Optional, for faster code search: ripgrep (e.g. winget install BurntSushi.ripgrep.MSVC)

Launchers: devmcp.ps1 / devmcp.bat (Windows) and devmcp.sh (Linux; run chmod +x devmcp.sh after cloning).

Setup

1. Clone the repository and install dependencies:

   pip install -r requirements.txt
   playwright install chromium
   

2. Reserve a domain in the ngrok dashboard and point the launcher at it:

   setx DEVMCP_NGROK_URL "https://your-domain.ngrok-free.dev"
   

   If unset, ngrok assigns a random URL each run (check the inspector at http://127.0.0.1:4040).

3. Add this folder to your PATH so devmcp works from anywhere.

4. Start it from a project folder:

   cd path/to/project
   devmcp
   

5. In your MCP client, add a server with:

   • URL: https://your-domain.ngrok-free.dev/mcp (the path must end in /mcp)
   • Transport: streamable HTTP
   • Auth: bearer token with any value (the server does no authentication itself)

Ctrl+C stops the server and the tunnel.

Configuration

Variable	Default	Meaning
DEVMCP_NGROK_URL	(unset)	Reserved ngrok domain used by the launcher
DEVMCP_PORT	8787	Local port for the server and tunnel
DEVMCP_HOST	127.0.0.1	Bind address for the server

All variables are optional — the server runs fine with the defaults. Instead of setting them globally, you can copy .env.example to .env next to the launcher and edit it there; both launchers load it automatically (.env is gitignored).

Output caps, ignored directories, and the browser user agent are constants at the top of dev_server.py.

Security

• File tools reject paths that escape the launch folder. Shell tools are not sandboxed — they run arbitrary commands with your user's privileges.
• There is no real authentication. Anyone with the tunnel URL can control your machine: keep the URL private and stop the tunnel when not in use.

Notes

• Commands that may run longer than ~60 seconds (dev servers, builds) should use start_process + check_process, not a blocking run_cmd.
• Every tool returns a readable ERROR (...) string instead of raising; a transport-level connection failure means the server or tunnel is down.
• After editing dev_server.py, call restart_server and retry tools after ~10 seconds.
• Most MCP clients cache the tool list at connect time — refresh the connection after adding or renaming tools.

Troubleshooting

Symptom	Fix
421 error on connect	ngrok is missing --host-header=localhost:<port> (the launcher sets it)
"Failed to connect" / timeouts	Server or tunnel not running (or mid-restart); wait ~10 s and retry, or rerun devmcp
Stray ngrok process	taskkill /F /IM ngrok.exe
Editor import warnings	Wrong Python interpreter selected, not a real error