Faber MCP Server
MCP (Model Context Protocol) server for deploying Laravel applications to Faber servers directly from Cursor.
Overview
Faber MCP enables you to deploy and manage Laravel applications on Faber servers using AI agents in Cursor. Simply ask your AI assistant to "deploy this project to production" and it handles the rest - including provisioning new stacks, managing GitHub deploy keys, and triggering deployments.
Features
- Deploy Laravel apps from Cursor with natural language commands
- Available globally across all your projects
- Multi-server support (production, staging, etc.)
- Automatic GitHub deploy key setup via Device Flow OAuth
- Full stack management (apps, domains, databases, SSL)
- Release management and rollbacks
- Real-time logs and debugging
Installation
Option 1: Install from npm (when published)
npm install -g faber-mcp
Option 2: Install from source
git clone https://github.com/JoshTrebilco/faber-mcp.git
cd faber-mcp
npm install
npm run build
npm link # Makes it available globally
Configuration
Step 1: Create Server Configuration
Create ~/.faber-mcp.json with your Faber server details.
You can copy example-config.json as a starting point:
cp example-config.json ~/.faber-mcp.json
# Edit with your server details
nano ~/.faber-mcp.json
Or create it from scratch:
{
"defaultServer": "production",
"servers": {
"production": {
"host": "your-production-server.com",
"user": "root",
"keyPath": "~/.ssh/id_rsa",
"port": 22
},
"staging": {
"host": "staging.example.com",
"user": "root",
"keyPath": "~/.ssh/id_rsa"
}
}
}
Requirements:
- SSH key must have access to the Faber server
faberCLI must be installed on the server- You must be able to authenticate as root
Step 2: Configure Cursor
Edit ~/.cursor/mcp.json (create if it doesn't exist):
{
"mcpServers": {
"faber": {
"command": "faber-mcp"
}
}
}
Alternative configurations:
If Cursor can't find the global command, use the full path:
{
"mcpServers": {
"faber": {
"command": "node",
"args": ["/usr/local/lib/node_modules/faber-mcp/dist/index.js"]
}
}
}
Or use npx (no global install needed):
{
"mcpServers": {
"faber": {
"command": "npx",
"args": ["-y", "faber-mcp"]
}
}
}
Important: Restart Cursor completely after adding the MCP server configuration.
Usage Examples
Deploy Current Project
Simply ask Cursor's AI agent:
"Deploy this project to production"
The agent will:
- Check if the app already exists on the server
- If not, prompt you for:
- Project name (username in Faber)
- Git repository URL
- Domain name
- PHP version
- Git branch
- Create the full stack (app, domain, database, SSL, .env)
- GitHub Authorization (if GitHub OAuth is configured on server):
-
Cursor will display a message like:
GitHub Authorization Required 1. Open: https://github.com/login/device 2. Enter code: A1B2-C3D4 Waiting for authorization... -
Click the verification URI and enter the code
-
Authorize the application in your browser
-
Server automatically adds the deploy key to your repository
-
- Or if the app exists, trigger a deployment
Other Commands
"Check if myapp is deployed on production"
"List all apps on the production server"
"Rollback myapp to the previous release"
"Show me the production server status"
"Deploy this to staging server"
Multi-Server Support
When using multiple servers, specify which one:
"Deploy this to staging server"
The agent will use the staging profile from your config. If not specified, it uses defaultServer.
Available Tools
The MCP server provides these tools to Cursor's AI agent:
App Management
faber_check_app- Check if an app exists and get detailsfaber_list_apps- List all deployed appsfaber_create_stack- Create full application stack (handles GitHub deploy key setup)faber_deploy- Trigger zero-downtime deploymentfaber_get_deploy_key- Retrieve SSH public key for an app (for manual GitHub setup)
Server Management
faber_server_status- Get server health and service statusfaber_service_restart- Restart services (nginx, php, mysql, redis)
Domain Management
faber_list_domains- List configured domainsfaber_create_domain- Create/assign domain to app
Database Management
faber_list_databases- List all databasesfaber_create_database- Create a new database
Release Management
faber_list_releases- List available releases for an appfaber_rollback- Rollback to a previous release
Logs & Debugging
faber_webhook_logs- View webhook execution logsfaber_app_logs- View Laravel application logs
Environment
faber_get_env- Read .env file (read-only)faber_set_env_var- Set a specific .env variable
Troubleshooting
MCP server not connecting
- Verify SSH key has access:
ssh -i ~/.ssh/id_rsa root@your-server.com - Check
~/.faber-mcp.jsonsyntax is valid JSON - Ensure
faberCLI is installed on the server:ssh root@server "which faber"
Cursor not recognizing tools
- Restart Cursor completely after adding MCP config
- Check Cursor's MCP logs: View → Output → Select "MCP" from dropdown
- Verify the path in
~/.cursor/mcp.jsonis correct and absolute
SSH connection errors
- Test SSH connection manually first
- Ensure SSH key permissions:
chmod 600 ~/.ssh/id_rsa - Check server firewall allows SSH on port 22
Faber commands failing
- Verify you're running as root on the server
- Check Faber is installed:
ssh root@server "faber version" - Review server logs:
ssh root@server "faber logs"
Requirements
- Node.js 18+ (for running the MCP server locally)
- SSH access to Faber server(s)
- Faber CLI installed on target server(s)
- Cursor IDE with MCP support
Development
# Clone the repository
git clone https://github.com/JoshTrebilco/faber-mcp.git
cd faber-mcp
# Install dependencies
npm install
# Build TypeScript
npm run build
# Or watch mode
npm run dev
License
MIT
Links
- Faber Server - Laravel server management CLI
- MCP Protocol - Model Context Protocol specification