# Forge MCP Server This is a Model Context Protocol (MCP) server for Laravel Forge integration. It provides comprehensive access to Laravel Forge's official API through MCP-compliant tools, enabling seamless server and site management. For more information about the Laravel Forge API, see the [official API documentation](https://forge.laravel.com/api-documentation). ## Features - MCP-compliant server - Comprehensive Laravel Forge API integration - Health check tool: `test_connection` - Extensive tool coverage for server and site management - Built on Laravel Forge's official API ## Prerequisites - Node.js (v18+ recommended) - npm (v9+ recommended) ## Configuration & Usage A **Forge API key is required** for all Forge tool invocations. You must provide it as either: - the `FORGE_API_KEY` environment variable, **or** - the `--api-key` command-line argument ### Usage with Claude Desktop Add the following to your `claude_desktop_config.json`. See [here](https://modelcontextprotocol.io/quickstart/user) for more details. #### Option 1: Using npx (Recommended) **Using environment variable:** ```json { "mcpServers": { "forge-mcp": { "command": "npx", "args": [ "-y", "@ranium/forge-mcp" ], "env": { "FORGE_API_KEY": "your_forge_api_key_here" } } } } ``` **Using command-line argument:** ```json { "mcpServers": { "forge-mcp": { "command": "npx", "args": [ "-y", "@ranium/forge-mcp", "--api-key=your_forge_api_key_here" ] } } } ``` #### Option 2: Using node directly First, clone the repository and build the project: ```sh git clone https://github.com/ranium/forge-mcp-server cd forge_mcp npm install npm run build ``` Then add the following to your `claude_desktop_config.json`: **Using environment variable:** ```json { "mcpServers": { "forge-mcp": { "command": "node", "args": [ "/path/to/forge_mcp/dist/server.js" ], "env": { "FORGE_API_KEY": "your_forge_api_key_here" } } } } ``` **Using command-line argument:** ```json { "mcpServers": { "forge-mcp": { "command": "node", "args": [ "/path/to/forge_mcp/dist/server.js", "--api-key=your_forge_api_key_here" ] } } } ``` **Note:** You can use either the `FORGE_API_KEY` environment variable or the `--api-key` argument. If both are provided, the command-line argument takes precedence. Never commit your real API keys to version control. Use environment variables or secrets management in production. ## Tool Categories & Access Control All tools are grouped into two categories: - **Readonly**: Safe, non-modifying operations (e.g., listing, viewing, status checks). - **Write**: Operations that create or modify resources (e.g., create, update, reboot, enable/disable features). By default, **only readonly tools are enabled**. To enable write tools, use the `--tools` flag: - `--tools=readonly` (default) - `--tools=readonly,write` (enables readonly and write tools) **Example:** ```sh npx -y @ranium/forge-mcp --api-key=your_forge_api_key_here --tools=readonly,write ``` Or in `claude_desktop_config.json`: ```json { "mcpServers": { "forge-mcp": { "command": "npx", "args": [ "-y", "@ranium/forge-mcp", "--api-key=your_forge_api_key_here", "--tools=readonly,write" ] } } } ``` ## Available Tools (by Category) ### Readonly Tools - `list_servers` - List all servers - `list_static_php_versions` - List static PHP versions - `list_php_versions` - List PHP versions - `get_user` - Get user information - `show_server` - Get detailed information about a specific server - `list_sites` - List all sites on a server - `show_site` - Get detailed information about a specific site - `list_daemons` - List daemons - `show_daemon` - Get daemon details - `list_deployments` - List deployments - `get_deployment_log` - Get deployment logs - `get_deployment` - Get deployment details - `get_deployment_output` - Get deployment output - `get_server_logs` - Get server logs - `list_providers` - List cloud providers - `list_database_types` - List database types - `list_credentials` - List credentials - `list_regions` - List available regions - `list_ubuntu_versions` - List Ubuntu versions - `get_composer_packages_auth` - Get Composer authentication - `check_laravel_maintenance_status` - Check Laravel maintenance mode - `check_pulse_daemon_status` - Check Pulse daemon status - `check_inertia_daemon_status` - Check Inertia daemon status - `check_laravel_scheduler_status` - Check Laravel scheduler status - `list_sizes` - List server sizes - `list_project_types` - List project types - `list_databases` - List all databases - `get_database` - Get database details - `list_database_users` - List database users - `get_database_user` - Get database user details - `list_certificates` - List SSL certificates - `get_certificate` - Get certificate details - `get_site_env` - Get site environment file (.env) - `get_site_log` - Get site logs ### Write Tools - `create_server` - Create a new server - `create_database` - Create a new database - `sync_database` - Sync database - `create_database_user` - Create a new database user - `reboot_server` - Reboot a server - `reboot_nginx` - Reboot Nginx service - `reboot_php` - Reboot PHP service - `reboot_mysql` - Reboot MySQL service - `reboot_postgres` - Reboot PostgreSQL service - `create_site` - Create a new site - `install_or_update_site_git` - Install or update Git repository - `enable_quick_deployment` - Enable quick deployment - `disable_quick_deployment` - Disable quick deployment - `deploy_now` - Deploy immediately - `change_site_php_version` - Change site PHP version - `add_site_aliases` - Add site aliases - `clear_site_log` - Clear site logs - `create_lets_encrypt_certificate` - Create Let's Encrypt certificate - `activate_certificate` - Activate a certificate ## Screenshots ### Creating a Server ![Creating a Server](docs/screenshots/create-server.png) *Demonstrates the server creation process through the MCP interface* ### Creating a Site ![Creating a Site](docs/screenshots/create-site.png) *Shows how to create a new site on an existing server* ### Rebooting a Server ![Rebooting a Server](docs/screenshots/reboot-server.png) *Illustrates the server reboot functionality* ## Project Structure - `src/server.ts` — Main MCP server entry point - `src/tools/forge/` — All Forge tool definitions and registry - `src/core/types/` — Type definitions and protocols - `package.json` — Scripts and dependencies - `.gitignore` — Ignores build, env, and dependency files ## Extending (Adding New Tools) 1. Export a `ForgeToolDefinition` from the new file. 2. Import and add the tool to the `forgeTools` array in `src/tools/forge/index.ts`. 3. The tools will be registered when the server starts. --- For more information on MCP, see the [Model Context Protocol documentation](https://modelcontextprotocol.org/). ## Disclaimer Forge MCP server is an independent product and not officially affiliated with, endorsed by, or sponsored by Laravel or Taylor Otwell. 'Laravel' is a registered trademark owned by Taylor Otwell. Forge MCP server is developed and maintained independently from the official Laravel project. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details.