VibeShell: MCP for PHP on shared hosting (a.k.a. “vibe code in any LAMP”)

If you’ve been watching the agentic tooling wave, you already know the annoying part: most “AI integrations” assume you’re running Docker, have root, or want to rebuild your stack around somebody else’s platform.

VibeShell goes the opposite direction.

It’s a single-file PHP MCP server you can drop onto basically any LAMP/LEMP host, then let an MCP-capable assistant securely read/write/list/search/tail files and logs—without adding dependencies. GitHub

What VibeShell is (and why it exists)

VibeShell is a lightweight, PHP 7.4+ implementation of the Model Context Protocol (MCP) over JSON-RPC 2.0 via HTTP, designed to give an AI assistant a safe toolbox for file operations. GitHub+1

If you read our MCP write-up, you know our stance: you shouldn’t need containers to ship a small project, and you shouldn’t have to “trust magic” to automate your hosting. Opalstack

VibeShell fits that philosophy: show me the wires.

What it can do

VibeShell exposes a small set of practical tools—enough to be useful, not enough to be scary:

• fs_info (paths: home/base/apps/logs)
• fs_list (list dirs, optional recursion)
• fs_read (read file contents with offset/limit)
• fs_write (write/append + auto-mkdir)
• fs_tail (tail logs)
• fs_search (recursive grep)
• fs_move (move/rename)
• fs_delete (delete, optional recursive) GitHub

And it comes with guardrails: home-directory jail, realpath() resolution to prevent symlink escapes, traversal blocking, protected files, rate limiting, and bearer-token auth. GitHub

Quick start: deploy VibeShell on Opalstack (or anywhere)

1) Upload the file

You literally upload index.php to a directory your web server can hit. The README shows the idea: GitHub

# Example: deploy to your app directory
scp index.php user@yourserver:~/apps/mcp/

2) Create the config

VibeShell reads a simple INI in your home directory:

cat > ~/.mcp_vibeshell.ini << 'EOF'
[vibeshell]
token = "your-secure-token-here"
base_dir = "~"
EOF

chmod 600 ~/.mcp_vibeshell.ini

Token + base_dir are the big knobs. If you want to be extra sane, set base_dir="~/apps" so the agent can’t wander. GitHub

Generate a token the boring way:

openssl rand -hex 20

3) Point your MCP client at it

Example MCP client config (VS Code / agent / whatever you’re using):

{
"mcpServers": {
"vibeshell": {
"type": "http",
"url": "https://your-domain.com/mcp/",
"headers": {
"Authorization": "Bearer your-secure-token-here"
}
}
}
}

That matches the repo’s recommended setup. GitHub

Test it with curl (because you should)

Initialize:

curl -X POST https://your-domain.com/mcp/ \
-H "Authorization: Bearer your-token" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}'

List tools:

curl -X POST https://your-domain.com/mcp/ \
-H "Authorization: Bearer your-token" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Call a tool (fs_list):

curl -X POST https://your-domain.com/mcp/ \
-H "Authorization: Bearer your-token" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"fs_list","arguments":{"path":"~"}}}'

All straight from the README. GitHub

The “don’t be dumb” security checklist

Agentic tooling is powerful because it can do real work. That’s also the risk.

• Use HTTPS (VibeShell recommends it for production). GitHub
• Use a real token (bearer auth is built-in). GitHub
• Restrict base_dir if you can. GitHub
• Treat your MCP token like prod credentials (because it is).

If you’ve used our Opalstack MCP endpoint, the mental model is the same: tokens are granular, and an agent can absolutely do destructive things if you let it. Opalstack

Why we like this

VibeShell is the kind of integration we’re into:

• No platform lock-in
• No container tax
• No mystery meat
• Works on boring hosting (shared accounts, legacy apps, the stuff people actually run) GitHub+1

If you want “AI that can actually help maintain real servers,” start here.