npm package: @g99/gridpane-mcp-server
Description: Model Context Protocol (MCP) server for GridPane OAuth API - Manage servers, sites, domains, users, and more
Author: GridPane MCP Contributors
Latest version: 1.0.7

# GridPane MCP Server

A Model Context Protocol (MCP) server for the GridPane OAuth API. This server enables AI assistants and tools to interact with GridPane's hosting management platform to manage servers, WordPress sites, domains, backups, and more.

## Features

- **Complete GridPane API Coverage**: Access all major GridPane API endpoints
- **45+ Tools**: Comprehensive toolset for server and site management
- **OAuth Authentication**: Secure API access using bearer tokens
- **Easy Installation**: Install via npx
- **TypeScript**: Fully typed for better development experience

## Installation

### Using npx (Recommended)

```bash
npx @g99/gridpane-mcp-server
```

### Using npm (Global Installation)

```bash
npm install -g @g99/gridpane-mcp-server
```

## Configuration

### Environment Variables

Create a `.env` file or set the following environment variables:

```env
# Optional: Your GridPane instance URL (defaults to https://my.gridpane.com)
GRIDPANE_API_URL=https://my.gridpane.com

# Required: Your GridPane Personal Access Token
GRIDPANE_API_TOKEN=your_gridpane_api_token_here
```

### Getting Your API Token

1. Log in to your GridPane account at https://my.gridpane.com (or your custom instance URL)
2. Navigate to **Account Settings** → **API Access**
3. Generate a new **Personal Access Token**
4. Copy the token and use it as your `GRIDPANE_API_TOKEN`

**Note:** If you're using a custom GridPane instance (not the default my.gridpane.com), set `GRIDPANE_API_URL` to your instance URL.

## MCP Client Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gridpane": {
      "command": "npx",
      "args": ["-y", "@g99/gridpane-mcp-server"],
      "env": {
        "GRIDPANE_API_URL": "https://my.gridpane.com",
        "GRIDPANE_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

### Cline (VS Code Extension)

Add to your MCP settings:

```json
{
  "mcpServers": {
    "gridpane": {
      "command": "npx",
      "args": ["-y", "@g99/gridpane-mcp-server"],
      "env": {
        "GRIDPANE_API_URL": "https://my.gridpane.com",
        "GRIDPANE_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

## Available Tools

### User Management (2 tools)

- `get_current_user` - Get authenticated user information
- `get_user_integrations` - Get user's integrations

### Server Management (5 tools)

- `list_servers` - List all servers
- `get_server` - Get server details
- `create_custom_server` - Create a new custom server
- `delete_server` - Delete a server
- `get_server_plans` - Get available server plans for providers (DigitalOcean, Vultr, Linode, UpCloud, AWS Lightsail)

### Site Management (5 tools)

- `list_sites` - List all WordPress sites
- `get_site` - Get site details
- `create_site` - Create a new WordPress site
- `delete_site` - Delete a site
- `clone_site` - Clone a site to a new location

### Domain Management (4 tools)

- `list_domains` - List all domains
- `get_domain` - Get domain details
- `add_domain` - Add a domain to a site
- `remove_domain` - Remove a domain

### System User Management (3 tools)

- `list_system_users` - List system users
- `create_system_user` - Create a new system user
- `delete_system_user` - Delete a system user

### Team Management (3 tools)

- `list_teams` - List all teams
- `get_team` - Get team details
- `create_team` - Create a new team

### Bundle Management (3 tools)

- `list_bundles` - List plugin/theme bundles
- `get_bundle` - Get bundle details
- `apply_bundle_to_site` - Apply a bundle to a site

### Backup Management (5 tools)

- `list_backups` - List all backups
- `get_backup` - Get backup details
- `create_backup` - Create a new backup
- `restore_backup` - Restore from a backup
- `delete_backup` - Delete a backup

## Usage Examples

### Example 1: List All Servers

```typescript
// Using the MCP tool
await use_mcp_tool("gridpane", "list_servers", {});
```

### Example 2: Create a New WordPress Site

```typescript
await use_mcp_tool("gridpane", "create_site", {
  server_id: "srv_123456",
  domain: "example.com",
  wp_username: "admin",
  wp_email: "admin@example.com",
  site_title: "My Awesome Site"
});
```

### Example 3: Create a Backup

```typescript
await use_mcp_tool("gridpane", "create_backup", {
  site_id: "site_123456",
  backup_type: "full"
});
```

### Example 4: Clone a Site

```typescript
await use_mcp_tool("gridpane", "clone_site", {
  site_id: "site_123456",
  new_domain: "staging.example.com",
  target_server_id: "srv_789012" // Optional
});
```

## Development

### Prerequisites

- Node.js 18 or higher
- npm or yarn

### Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/gridpane-mcp-server.git
cd gridpane-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev
```

### Testing

```bash
# Set your API token
export GRIDPANE_API_TOKEN=your_token_here

# Run the server
npm start
```

## API Reference

This MCP server implements the GridPane OAuth API v1. For detailed API documentation, visit:

- Official API Docs: https://gridpane.com/api-docs
- Postman Collection: https://documenter.getpostman.com/view/13664964/TVssjU7Z

## Requirements

- **GridPane Account**: Active GridPane account with API access
- **API Token**: Personal access token from GridPane dashboard
- **Node.js**: Version 18.0.0 or higher
- **MCP Client**: Compatible MCP client (Claude Desktop, Cline, etc.)

## Security Best Practices

1. **Never commit your API token** to version control
2. **Use environment variables** for sensitive credentials
3. **Rotate tokens regularly** for enhanced security
4. **Limit token permissions** to only what's necessary
5. **Monitor API usage** through GridPane dashboard

## Troubleshooting

### Error: GRIDPANE_API_TOKEN environment variable is required

Make sure you've set the required environment variables:

```bash
export GRIDPANE_API_URL=https://my.gridpane.com  # Optional, defaults to my.gridpane.com
export GRIDPANE_API_TOKEN=your_token_here        # Required
```

### Error: Authentication failed

Verify that:
1. Your API token is valid and not expired
2. Your GridPane account has API access enabled
3. The token has the necessary permissions

### Error: Tool not found

Ensure you're using the correct tool name. Run `list_tools` to see all available tools.

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- **Issues**: https://github.com/yourusername/gridpane-mcp-server/issues
- **Documentation**: https://github.com/yourusername/gridpane-mcp-server#readme
- **GridPane Support**: https://gridpane.com/support

## Acknowledgments

- Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
- Powered by [GridPane API](https://gridpane.com/api-docs)
- Created for the MCP community

## Changelog

### Version 1.0.0 (Initial Release)

- ✅ Complete GridPane API integration
- ✅ 30+ management tools
- ✅ OAuth authentication
- ✅ Full TypeScript support
- ✅ Comprehensive documentation
- ✅ NPX and UVX installation support

---

**Made with ❤️ for the GridPane and MCP communities**