# Gandi MCP Server
[](https://badge.fury.io/js/@artik0din%2Fmcp-gandi)
[](https://opensource.org/licenses/MIT)
[](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/)
