npm package: @neivi/iqx-lookup-mcp-server
Description: MCP server for IQX Lookup Platform — 12 data validation tools for AI agents: email, phone, EU VAT (VIES), IBAN, BIC, DNS, SSL, IP geolocation, and more. Free tier: 10K req/month.
Author: Neivi IT
Latest version: 0.3.0

# IQX Lookup — Data Validation MCP Server

12 validation and lookup tools for AI agents. European-first: EU VAT (VIES), IBAN, BIC/SWIFT, plus email, phone, DNS, SSL, IP geolocation, password strength, credit card, and user agent parsing.

[![npm version](https://img.shields.io/npm/v/@neivi/iqx-lookup-mcp-server)](https://www.npmjs.com/package/@neivi/iqx-lookup-mcp-server)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

## Free Tier

No credit card required. 30-second signup.

| Limit | Value |
|-------|-------|
| Requests / month | 10,000 |
| Requests / day | 1,000 |
| Requests / minute | 60 |
| API tokens | 5 |
| Cost | **$0** |

Get your API key at **[dashboard.iqxlookup.neivi.es](https://dashboard.iqxlookup.neivi.es)**.

## Quick Start

### Claude Desktop

Add to `~/.config/claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "iqx-lookup": {
      "command": "npx",
      "args": ["-y", "@neivi/iqx-lookup-mcp-server"],
      "env": {
        "LOOKUP_API_KEY": "ALk-your-api-key"
      }
    }
  }
}
```

### Claude Code

Add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "iqx-lookup": {
      "command": "npx",
      "args": ["-y", "@neivi/iqx-lookup-mcp-server"],
      "env": {
        "LOOKUP_API_KEY": "ALk-your-api-key"
      }
    }
  }
}
```

### Cursor / Windsurf

Add to your MCP configuration (Settings > MCP Servers):

```json
{
  "mcpServers": {
    "iqx-lookup": {
      "command": "npx",
      "args": ["-y", "@neivi/iqx-lookup-mcp-server"],
      "env": {
        "LOOKUP_API_KEY": "ALk-your-api-key"
      }
    }
  }
}
```

## Get Your API Key

1. Sign up at [dashboard.iqxlookup.neivi.es](https://dashboard.iqxlookup.neivi.es) (email + password, no credit card)
2. Go to **API Keys** and create a new token
3. Copy the key (starts with `ALk-`) and set it as `LOOKUP_API_KEY`

## Available Tools

| Tool | Description |
|------|-------------|
| `validate_email` | Email deliverability: MX records, disposable/free provider detection, role address check |
| `validate_phone` | Phone validation: E.164 format, carrier, line type (mobile/landline/VoIP), timezone |
| `geolocate_ip` | IP geolocation: country, city, coordinates, ISP, timezone, EU membership |
| `geolocate_my_ip` | Geolocate the server's own public IP address |
| `validate_vat` | EU VAT validation against VIES (27 member states): company name, address |
| `parse_useragent` | User-Agent parsing: browser, OS, device type, bot detection |
| `validate_iban` | IBAN validation: structure, MOD 97-10 checksum, bank/branch identification |
| `validate_bic` | BIC/SWIFT validation: format, institution, country, branch |
| `lookup_dns` | DNS lookup: A, AAAA, MX, TXT, CNAME, NS, SOA + SPF/DKIM/DMARC analysis |
| `check_password_strength` | Password strength: zxcvbn score (0-4), crack time, breach check (k-anonymity) |
| `check_ssl_certificate` | SSL/TLS inspection: issuer, expiry, SANs, chain, grade (A+ to F) |
| `validate_credit_card` | Credit card validation: Luhn check, network ID, BIN lookup (never returns full number) |

## European Validation Strength

This server is uniquely positioned for European data validation:

- **EU VAT (VIES)**: Real-time validation against the official EU VIES service across all 27 member states
- **IBAN**: Structural validation + MOD 97-10 checksum + bank identification for European banking
- **BIC/SWIFT**: Institution lookup across European and global banking networks
- **Phone**: European number formats with carrier and operator identification

No other MCP server covers this combination of European financial and telecom validation.

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `LOOKUP_API_KEY` | Yes | -- | API key from [IQX Lookup](https://dashboard.iqxlookup.neivi.es) (free tier available) |
| `LOOKUP_BASE_URL` | No | `https://api.iqxlookup.neivi.es` | API base URL (override for self-hosted or testing) |

The API key can also be passed as the first CLI argument:

```bash
npx @neivi/iqx-lookup-mcp-server ALk-your-api-key
```

## Rate Limits

Every successful response includes rate limit headers:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Maximum requests in the current window |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |

When rate-limited (HTTP 429), the server returns a structured error with the `Retry-After` delay. The MCP error message guides the AI agent to space out requests.

## Example Conversations

**Verifying a business partner's EU credentials:**

> "Validate the VAT number DE123456789 and check if their domain example.de has valid SSL."

The assistant calls `validate_vat` and `check_ssl_certificate`, returning the VIES registration status and the certificate expiry date in a single response.

**Investigating a suspicious signup:**

> "This user signed up with email test@tempmail.org from IP 203.0.113.42. Is this legitimate?"

The assistant calls `validate_email` (flags disposable provider) and `geolocate_ip` (returns country and ISP), giving you a risk assessment based on both signals.

**Auditing payment form inputs:**

> "Check if DE89370400440532013000 is a valid IBAN, and also validate credit card 4111111111111111."

The assistant calls `validate_iban` (confirms valid structure, returns bank name) and `validate_credit_card` (passes Luhn, identifies Visa network).

## Error Handling

All errors are returned as structured messages that AI agents can interpret:

| Code | Description |
|------|-------------|
| `VALIDATION_ERROR` | Input validation failed (missing or malformed parameters) |
| `UNAUTHORIZED` | Missing or invalid API key |
| `RATE_LIMIT_EXCEEDED` | Too many requests -- includes retry delay |
| `QUOTA_EXCEEDED` | Monthly usage quota exhausted |
| `UPSTREAM_UNAVAILABLE` | External validation service temporarily unreachable |
| `SERVICE_UNAVAILABLE` | Lookup Platform temporarily unavailable |
| `INTERNAL_ERROR` | Unexpected server error |

## Docker

```bash
docker build -t iqx-lookup-mcp-server:latest .
docker run -i --rm -e LOOKUP_API_KEY=ALk-your-key iqx-lookup-mcp-server:latest
```

Use with Claude Desktop:

```json
{
  "mcpServers": {
    "iqx-lookup": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "LOOKUP_API_KEY=ALk-your-key",
        "iqx-lookup-mcp-server:latest"
      ]
    }
  }
}
```

## Development

```bash
npm install
npm run build
npm test          # 60 tests
npm run dev       # requires LOOKUP_API_KEY
```

Test interactively with the MCP Inspector:

```bash
npm run build
npx @modelcontextprotocol/inspector node dist/index.js
```

## License

[Apache-2.0](LICENSE) -- Copyright 2026 Neivi IT