# Gandi MCP Server

[![npm version](https://badge.fury.io/js/@artik0din%2Fmcp-gandi.svg)](https://badge.fury.io/js/@artik0din%2Fmcp-gandi)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)

A comprehensive [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for managing Gandi domains and DNS records via the Gandi API v5. This server enables AI assistants like Claude to manage domains and LiveDNS records directly through Gandi's API.

## Features

### 🌐 Domain Management
- **List Domains**: View all domains in your account
- **Domain Details**: Get comprehensive domain information
- **Domain Check**: Check domain availability for registration
- **Contact Management**: List domain contacts

### 📝 LiveDNS Management
- **DNS Records**: Full CRUD operations for DNS records
- **Record Types**: Support for A, AAAA, CNAME, MX, NS, PTR, SRV, TXT, CAA
- **Smart Filtering**: Filter records by type or name
- **TTL Control**: Manage record time-to-live settings

### 🛡️ Security & Reliability
- **Secure Authentication**: Environment-based API token management
- **Error Handling**: Comprehensive error handling with clear messages
- **Type Safety**: Full TypeScript support with proper type definitions

## Quick Start

Run the server directly with npx (requires Node.js 18+):

```bash
npx @artik0din/mcp-gandi
```

Or install locally:

```bash
npm install -g @artik0din/mcp-gandi
mcp-gandi
```

## Environment Variables

Create a `.env` file in your working directory:

| Variable | Required | Description |
|----------|----------|-------------|
| `GANDI_API_TOKEN` | ✅ | Your Gandi API token with domain and LiveDNS permissions |

### Getting Your Gandi API Token

1. Log in to [Gandi Dashboard](https://admin.gandi.net/)
2. Go to **Organizations > [Your Organization] > Billing & Cards**
3. Click on **Account Settings > Security**
4. In the **API Keys** section, click **Generate API keys**
5. Create a new API key with:
   - **Domain**: See and edit permissions
   - **LiveDNS**: See and edit permissions
   - **Billing**: See permission (optional, for domain pricing)

## MCP Client Configuration

### Claude Desktop

Add this to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "gandi": {
      "command": "npx",
      "args": ["@artik0din/mcp-gandi"],
      "env": {
        "GANDI_API_TOKEN": "your_api_token_here"
      }
    }
  }
}
```

### Other MCP Clients

Use the command `npx @artik0din/mcp-gandi` with the appropriate environment variables set.

## Available Tools

### Domain Management Tools

#### gandi_domains_list
List all domains in your Gandi account.

**Parameters:** None

**Example:**
```
List all my Gandi domains
```

#### gandi_domains_get
Get detailed information about a specific domain.

**Parameters:**
- `domain` (string, required): Domain name (e.g., example.com)

**Example:**
```
Get details for domain example.com
Show information about mydomain.net
```

#### gandi_domains_check
Check if a domain name is available for registration.

**Parameters:**
- `domain` (string, required): Domain name to check

**Example:**
```
Check if newdomain.com is available
Is example.org available for registration?
```

#### gandi_domains_contacts
List contacts associated with a domain.

**Parameters:**
- `domain` (string, required): Domain name

**Example:**
```
Show contacts for example.com
List contact information for mydomain.net
```

### DNS Management Tools

#### gandi_dns_records_list
List all DNS records for a domain.

**Parameters:**
- `domain` (string, required): Domain name
- `type` (string, optional): Filter by record type (A, AAAA, CNAME, MX, NS, PTR, SRV, TXT, CAA)

**Example:**
```
List all DNS records for example.com
Show A records for mydomain.net
Get MX records for example.org
```

#### gandi_dns_record_get
Get a specific DNS record by name and type.

**Parameters:**
- `domain` (string, required): Domain name
- `name` (string, required): Record name (e.g., www, @, subdomain)
- `type` (string, required): Record type

**Example:**
```
Get A record for www.example.com
Show CNAME record for blog subdomain of mydomain.net
```

#### gandi_dns_record_create
Create a new DNS record.

**Parameters:**
- `domain` (string, required): Domain name
- `name` (string, required): Record name (e.g., www, @, subdomain)
- `type` (string, required): Record type (A, AAAA, CNAME, MX, NS, PTR, SRV, TXT, CAA)
- `values` (array, required): Record values (IP addresses, hostnames, text content)
- `ttl` (number, optional): TTL in seconds (300-2592000, defaults to 300)

**Example:**
```
Create an A record for www pointing to 1.2.3.4 for example.com
Add CNAME record for blog pointing to www.example.com with TTL 3600
Create MX record for @ pointing to mail.example.com with TTL 1800
```

#### gandi_dns_record_update
Update an existing DNS record.

**Parameters:**
- `domain` (string, required): Domain name
- `name` (string, required): Record name
- `type` (string, required): Record type
- `values` (array, required): New record values
- `ttl` (number, optional): New TTL in seconds

**Example:**
```
Update A record for www.example.com to point to 5.6.7.8
Change TTL of CNAME record for blog.mydomain.net to 7200 seconds
Update MX record for example.org to use new mail server
```

#### gandi_dns_record_delete
Delete a DNS record.

**Parameters:**
- `domain` (string, required): Domain name
- `name` (string, required): Record name
- `type` (string, required): Record type

**Example:**
```
Delete A record for old.example.com
Remove CNAME record for staging subdomain
Delete old MX record for example.org
```

## DNS Record Types

The server supports all standard DNS record types:

- **A**: IPv4 address records
- **AAAA**: IPv6 address records  
- **CNAME**: Canonical name records (aliases)
- **MX**: Mail exchange records
- **NS**: Name server records
- **PTR**: Pointer records (reverse DNS)
- **SRV**: Service records
- **TXT**: Text records (SPF, DKIM, verification, etc.)
- **CAA**: Certification Authority Authorization records

## Security Considerations

- **API Token Security**: Never commit your API token to version control
- **Minimal Permissions**: Use API tokens with only the required permissions
- **Regular Rotation**: Rotate API tokens regularly for security
- **Environment Variables**: Always use environment variables for credentials
- **Domain Safety**: Be careful when deleting DNS records in production

## Error Handling

The server provides clear error messages for common scenarios:

- **Invalid API token**: Check your token and permissions
- **Domain not found**: Verify domain ownership and spelling
- **Record not found**: Check record name, type, and domain
- **Rate limiting**: Gandi API has rate limits; the server will indicate if you hit them
- **Invalid record data**: Validation errors for malformed DNS records

## Development

```bash
# Clone the repository
git clone https://github.com/artik0din/mcp-gandi.git
cd mcp-gandi

# Install dependencies
npm install

# Build the project
npm run build

# Run locally
npm start
```

## API Compatibility

This server is compatible with **Gandi API v5**. It uses:
- **Domain API**: For domain management operations
- **LiveDNS API**: For DNS record management

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Credits

Built with:
- [Model Context Protocol SDK](https://modelcontextprotocol.io/)
- [Gandi API v5](https://doc.livedns.gandi.net/)
- [Gandi Domain API](https://doc.gandi.net/domain/)