Netcup API MCP Server

A Model Context Protocol (MCP) server for the Netcup domain and DNS management API.

Features • Installation • Usage • Tools • Contributing

Manage your Netcup domains, DNS records, and contact handles directly through Claude Desktop using natural language. This MCP server provides seamless integration between Claude and the Netcup API.

Features

This MCP server brings the full power of Netcup's API to Claude, enabling you to:

Domain Management

• list_domains: List all domains in your Netcup account ⚠️ Reseller account required
• get_domain_info: Get detailed information about a specific domain ⚠️ Reseller account required
• get_domain_authcode: Retrieve the authorization code for domain transfers
• update_domain_nameservers: Update nameservers for a domain

DNS Management

• get_dns_zone: Get DNS zone information for a domain ✅ Works with all account types
• get_dns_records: Retrieve all DNS records for a domain ✅ Works with all account types
• update_dns_records: Update DNS records (A, AAAA, MX, CNAME, TXT, etc.) ✅ Works with all account types

Contact Handle Management

• get_contact_handle: Get information about a contact handle ⚠️ Reseller account required
• create_contact_handle: Create a new contact handle ⚠️ Reseller account required
• update_contact_handle: Update an existing contact handle ⚠️ Reseller account required
• delete_contact_handle: Delete a contact handle ⚠️ Reseller account required

Note: Some functions are only available for Netcup reseller accounts. DNS management functions work with all account types, including regular webhosting/VPS accounts.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Tool Reference
• Development
• Troubleshooting
• Contributing
• License

Prerequisites

• Node.js 18 or higher
• npm or yarn
• A Netcup account with API access
• Claude Desktop application

Installation

Option 1: Install from Source

1. Clone this repository:

git clone https://github.com/JensS/netcup-api-mcp.git
cd netcup-api-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Option 2: Using npx (Coming Soon)

Once published to npm, you'll be able to use:

npx netcup-api-mcp

Configuration

You need to provide your Netcup API credentials via environment variables:

• NETCUP_CUSTOMER_NUMBER: Your Netcup customer number
• NETCUP_API_KEY: Your API key (generated in the Netcup control panel)
• NETCUP_API_PASSWORD: Your API password (set in the Netcup control panel)

Getting API Credentials

1. Log in to your Netcup Customer Control Panel (CCP)
2. Navigate to the API section
3. Generate an API key if you haven't already
4. Set an API password

Usage

Setting up Claude Desktop

Add this configuration to your Claude Desktop config file:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "netcup": {
      "command": "node",
      "args": ["/absolute/path/to/netcup-api-mcp/build/index.js"],
      "env": {
        "NETCUP_CUSTOMER_NUMBER": "your-customer-number",
        "NETCUP_API_KEY": "your-api-key",
        "NETCUP_API_PASSWORD": "your-api-password"
      }
    }
  }
}

Replace:

• /absolute/path/to/netcup-api-mcp with the actual path to this project
• your-customer-number, your-api-key, and your-api-password with your actual credentials

Restart Claude Desktop

After adding the configuration, completely quit and restart Claude Desktop for the changes to take effect.

Example Interactions

Once configured, you can interact with your Netcup account using natural language:

Domain Management:

"List all my domains"
"What's the status of example.com?"
"Get the auth code for example.com so I can transfer it"
"Update the nameservers for example.com to ns1.example.net and ns2.example.net"

DNS Management:

"Show me all DNS records for example.com"
"Add an A record for www.example.com pointing to 192.0.2.1"
"Create an MX record for example.com with priority 10 pointing to mail.example.com"
"Update the TXT record for example.com to include my SPF record"
"Get the DNS zone information for example.com"

Contact Handle Management:

"Show me contact handle HANDLE123"
"Create a new contact handle for John Doe in Berlin, Germany"
"Update the email address for contact handle HANDLE123"
"Delete contact handle HANDLE456"

Tool Reference

list_domains

Lists all domains associated with your Netcup account.

Parameters: None

Example:

List all my domains

get_domain_info

Get detailed information about a specific domain.

Parameters:

• domain (string): The domain name (e.g., example.com)

Example:

Get information about example.com

get_domain_authcode

Retrieve the authorization code for a domain transfer.

Parameters:

• domain (string): The domain name (e.g., example.com)

Example:

Get the auth code for example.com

update_domain_nameservers

Update the nameservers for a domain.

Parameters:

• domain (string): The domain name (e.g., example.com)
• nameservers (array): Array of nameserver hostnames

Example:

Update nameservers for example.com to ns1.example.net and ns2.example.net

get_dns_zone

Get DNS zone information for a domain.

Parameters:

• domain (string): The domain name (e.g., example.com)

Example:

Get DNS zone info for example.com

get_dns_records

Get all DNS records for a domain.

Parameters:

• domain (string): The domain name (e.g., example.com)

Example:

Show me all DNS records for example.com

update_dns_records

Update DNS records for a domain. This replaces the entire DNS record set.

Parameters:

• domain (string): The domain name (e.g., example.com)
• records (array): Array of DNS record objects

Record Object Properties:

• id (string, optional): Record ID for updates
• hostname (string): The hostname (use @ for root domain)
• type (string): Record type (A, AAAA, MX, CNAME, TXT, etc.)
• priority (string, optional): Priority for MX records
• destination (string): The record value
• deleterecord (boolean, optional): Set to true to delete

Example:

Update DNS records for example.com to add an A record for www pointing to 192.0.2.1

get_contact_handle

Get information about a contact handle.

Parameters:

• handleId (string): The contact handle ID

Example:

Get contact handle information for HANDLE123

create_contact_handle

Create a new contact handle.

Parameters:

• type (string): Contact type (PERSON, ORG)
• name (string): Full name
• organization (string, optional): Organization name
• street (string): Street address
• postalcode (string): Postal code
• city (string): City
• countrycode (string): Two-letter country code
• telephone (string): Phone number
• email (string): Email address

Example:

Create a contact handle for John Doe, Mainstreet 1, 12345 Berlin, Germany

update_contact_handle

Update an existing contact handle.

Parameters: Same as create_contact_handle, plus:

• handleId (string): The contact handle ID to update

Example:

Update contact handle HANDLE123 with new email address

delete_contact_handle

Delete a contact handle.

Parameters:

• handleId (string): The contact handle ID to delete

Example:

Delete contact handle HANDLE123

Development

Contributions are welcome! Please see CONTRIBUTING.md for details.

Setup Development Environment

# Clone the repository
git clone https://github.com/JensS/netcup-api-mcp.git
cd netcup-api-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Watch for changes during development
npm run watch

Project Structure

netcup-api-mcp/
├── src/
│   ├── index.ts           # Main MCP server implementation
│   ├── netcup-client.ts   # Netcup API client wrapper
│   └── types.ts           # TypeScript type definitions
├── build/                 # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Testing

You can test the server by running it directly:

node build/index.js

The server communicates via stdio and expects JSON-RPC messages following the MCP protocol.

Security Notes

• Never commit your API credentials to version control
• Store credentials securely in your Claude Desktop config file
• API credentials are stored in environment variables, not in code
• Session management is handled automatically by the client
• All API requests require authentication
• Consider using read-only API keys when possible (if Netcup supports this)

Troubleshooting

Server Not Appearing in Claude Desktop

1. Verify the path in claude_desktop_config.json is absolute and correct
2. Ensure the build directory exists: ls build/index.js
3. Check that Node.js is in your PATH: which node
4. Completely quit and restart Claude Desktop (not just close the window)
5. Check Claude Desktop logs for errors

Error: Missing required environment variables

Make sure you've set all three required environment variables in your Claude Desktop config:

• NETCUP_CUSTOMER_NUMBER
• NETCUP_API_KEY
• NETCUP_API_PASSWORD

"The session-id is not in a valid format"

This error indicates an authentication problem. Debug steps:

1. Check Claude Desktop logs - The server now outputs detailed logging to help diagnose issues:

   • Look for [Netcup MCP] Configuration loaded to verify credentials are read
   • Look for [Netcup API] Attempting login and the response

2. Verify API credentials:

   • Customer number should be just the number (e.g., 123456)
   • API key is from the CCP API section
   • API password is the one you set (not your CCP login password)

3. Check credential format:

   "env": {
     "NETCUP_CUSTOMER_NUMBER": "123456",
     "NETCUP_API_KEY": "your-api-key-here",
     "NETCUP_API_PASSWORD": "your-api-password-here"
   }

4. Restart Claude Desktop completely after changing credentials

"This function is available for hosting products in a reseller account"

Some Netcup API functions are restricted to reseller accounts. If you have a regular webhosting or VPS account:

✅ These functions WILL work:

• get_dns_zone - Get DNS zone information
• get_dns_records - List DNS records
• update_dns_records - Update DNS records

⚠️ These functions require a RESELLER account:

• list_domains - List all domains
• get_domain_info - Get domain details
• get_domain_authcode - Get auth code
• update_domain_nameservers - Update nameservers
• Contact handle management functions

Workaround: If you only need DNS management (which most users do), use the DNS-related functions with your specific domain name.

Login Failed / Authentication Errors

If you receive authentication errors:

1. Verify your credentials are correct in the CCP
2. Ensure your API key is active in the Netcup control panel
3. Confirm your API password is set correctly (not your CCP login password)
4. Check that your customer number is correct
5. Check the server logs in Claude Desktop for detailed error messages

API Errors

If you receive API errors, check:

1. The domain exists in your account
2. You have permission to perform the requested operation
3. The API endpoints are accessible (check Netcup status page)
4. Your inputs are formatted correctly (e.g., valid domain names, IP addresses)

DNS Records Not Updating

When updating DNS records:

1. Get current records first to preserve existing ones
2. Remember that updates replace the entire record set
3. DNS changes may take time to propagate (up to 48 hours, usually much faster)
4. Verify the zone serial number increments after updates

Getting Help

• Check the Netcup API Documentation
• Open an issue on GitHub Issues
• Review existing issues for similar problems

API Documentation

For more information about the Netcup API:

• API Endpoint: https://ccp.netcup.net/run/webservice/servers/endpoint.php
• WSDL: https://ccp.netcup.net/run/webservice/servers/endpoint.php?WSDL
• JSON API: Add ?JSON parameter to the endpoint

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

See CONTRIBUTING.md for more information.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with the Model Context Protocol SDK
• Uses the Netcup API
• Inspired by the growing MCP server ecosystem

Support

If you find this project helpful, please consider:

• Starring the repository on GitHub
• Reporting bugs and suggesting features
• Contributing code or documentation improvements

⬆ back to top

Made with ❤️ for the MCP community