mcp-server

<p align="center">
   <img src="https://raw.githubusercontent.com/icedq-tools/mcp-server/master/icon.svg" alt="iceDQ Logo" width="80" />
</p>

<h1 align="center">iceDQ MCP Server</h1>

<p align="center">
  <strong>Connect your AI assistant to the iceDQ Data Reliability Platform</strong>
</p>

<p align="center">
  <a href="https://icedq.com">Website</a> &nbsp;&bull;&nbsp;
  <a href="https://docs.icedq.com/guides/mcp-server/intro">Documentation</a> &nbsp;&bull;&nbsp;
  <a href="mailto:getsupport@icedq.com">Support</a> &nbsp;&bull;&nbsp;
  <a href="https://icedq.com/privacy-policy">Privacy Policy</a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/version-2.0.0-blue.svg" alt="Version" />
  <img src="https://img.shields.io/badge/license-Apache--2.0-green.svg" alt="License" />
  <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS-lightgrey.svg" alt="Platform" />
</p>


---

## How It Works?

The iceDQ MCP Server connects **Claude Desktop**, **VS Code**, **Cursor**, and **Claude Code** to your
**iceDQ Data Reliability Platform** instance, letting you manage data quality using natural language.
Ask your AI assistant to explore databases, files, or REST APIs; profile data; and create
**Validation**, **Duplicate**, **Checksum**, **Pushdown**, and **Reconciliation** rules (including API
Validation and API Recon) — then execute, monitor, and analyze results, all through conversation.

Rules created through MCP tools are **published immediately** and ready to execute. The server also
bundles eight agent skills (`skills/`) that guide authoring, comparison, API testing, runs, and
schedules. Parameter names and schemas are listed in [TOOLS.md](TOOLS.md).

**49 tools** covering the full data quality lifecycle:

| Capability                 | What you can do                                                                                  |
|----------------------------|--------------------------------------------------------------------------------------------------|
| **Data Exploration**       | Browse workspaces, connections, databases, schemas, tables, columns, files, and REST APIs        |
| **Data Profiling**         | Fetch real sample data and analyze quality metrics (nulls, patterns, types)                      |
| **AI Suggestions**         | Get intelligent check recommendations based on your data profile                                 |
| **Validation Rules**       | Row-level NotNull, Format, ValidValues, Length, Date, and Custom Groovy checks on DB, files, or APIs |
| **Duplicate Detection**    | Identify duplicates on business keys, composite keys, or conditional criteria                    |
| **Pushdown Rules**         | SQL-driven aggregate validation (GROUP BY, JOINs, referential integrity)                         |
| **Checksum Rules**         | Cross-source comparison (row counts, sums) between two different connections                     |
| **Reconciliation**         | Row-level matching across databases, files, and APIs, with AI-powered join-key mapping           |
| **Workflows**              | Chain multiple rules into sequential execution workflows                                         |
| **Schedules**              | Automate rule execution with one-time, daily, or weekly schedules                                |
| **Custom Functions**       | Create and update Java/Groovy UDFs (Evaluator or Processor type)                                 |
| **Data Warehouse Queries** | Run structured, schema-validated queries against iceDQ's execution history datasets              |
| **Execution & Monitoring** | Run rules on demand, track status, and view exception reports                                    |
| **Organization**           | Manage folders, move rules in batch, create reusable parameters                                  |

---

## System Requirements

| Requirement          | Details                                                           |
|----------------------|-------------------------------------------------------------------|
| **Operating System** | Windows 10+, macOS 10.15+, or Linux *(see note below)*            |
| **AI Client**        | One of: Claude Desktop, VS Code, or Cursor (latest version)       |
| **Node.js**          | 20.0.0+ *(required for npx-based setup; the Claude Desktop extension bundles its own runtime)* |
| **iceDQ**            | v7.5.0+ with a valid user account                                 |

> **Linux users:** Install via the npx method (works in VS Code and Cursor). The packaged Claude Desktop extension (`.mcpb`) is currently macOS and Windows only because Claude Desktop itself does not ship a Linux build.

---

## Quick Start

### Step 1 — Get Your iceDQ Credentials

You need six values from your iceDQ instance before you can configure the MCP server:

- iceDQ Base URL
- Realm (default `iam.icedq`)
- Client ID and Client Secret (created in iceDQ → Administration → Security → Client Credentials)
- Your iceDQ username and password
- Organization ID (read from any rule's metadata)

For step-by-step instructions with screenshots, see the [Credentials Guide](docs/guides/mcp-server/CREDENTIALS.md).

### Step 2 — Install via npm

The iceDQ MCP Server is published on npm as **[`@icedq/mcp-server`](https://www.npmjs.com/package/@icedq/mcp-server)**. Most AI clients can launch it automatically with `npx` — no manual download or build step required.

Add the following to your AI client's MCP configuration:

```json
{
  "mcpServers": {
    "icedq": {
      "command": "npx",
      "args": ["-y", "@icedq/mcp-server"],
      "env": {
        "ICEDQ_BASE_URL": "https://app.icedq.net",
        "ICEDQ_REALM": "iam.icedq",
        "ICEDQ_CLIENT_ID": "<your-client-id>",
        "ICEDQ_CLIENT_SECRET": "<your-client-secret>",
        "AUTH_TYPE": "username_password",
        "ICEDQ_USERNAME": "<your-username>",
        "ICEDQ_PASSWORD": "<your-password>",
        "ICEDQ_ORG_ID": "<your-org-id>",
        "NODE_OPTIONS": "--use-system-ca"
      }
    }
  }
}
```

#### Configuration Reference

| Variable              | Required                   | Description                                                          |
|-----------------------|-----------------------------|------------------------------------------------------------------------|
| `ICEDQ_BASE_URL`      | Yes                        | Base URL of your iceDQ instance (e.g. `https://app.icedq.net`)       |
| `ICEDQ_REALM`         | Yes                        | Authentication realm (default `iam.icedq`)                           |
| `ICEDQ_CLIENT_ID`     | Yes                        | OAuth client ID for API authentication                               |
| `AUTH_TYPE`           | Yes                        | `username_password`, `access_token`, or `device_flow`                |
| `ICEDQ_ORG_ID`        | Yes                        | Your iceDQ organization ID                                           |
| `ICEDQ_CLIENT_SECRET` | For `username_password`    | OAuth client secret                                                  |
| `ICEDQ_USERNAME`      | For `username_password`    | Your iceDQ username                                                  |
| `ICEDQ_PASSWORD`      | For `username_password`    | Your iceDQ password                                                  |
| `TOKENS_PATH`         | For `access_token`         | Path to a token JSON file with `accessToken` and `refreshToken`      |
| `REMEMBER_ME`         | Optional, for `device_flow`| Defaults to remembering the cached session. Set to `false` to wipe stored tokens and force a fresh browser login |
| `VERIFY_SSL`          | Optional                   | Defaults to `true`. Set to `false` only for self-signed certificates |
| `REQUEST_TIMEOUT`     | Optional                   | API request timeout in seconds (default `30`)                        |
| `DEBUG`               | Optional                   | Set to `true` for verbose logging                                    |
| `LOG_LEVEL`           | Optional                   | `error`, `warn`, `info`, or `debug` (default `info`)                 |
| `NODE_OPTIONS`        | Optional                   | Set to `--use-system-ca` so Node trusts your OS certificate store (needed if your iceDQ instance uses a corporate/self-signed CA) |

> **Claude Desktop users** can install the packaged extension instead of editing JSON — follow the setup guide below.

#### Alternative: Device Flow Authentication (no password required)

Instead of supplying a username and password, you can authenticate via **Device Flow** ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) — the server opens a browser login page for you, and tokens are cached securely in your OS keychain (Windows Credential Manager, macOS Keychain, or Linux libsecret) so you only log in once. This is the recommended option for SSO/MFA-enabled accounts or shared machines where you don't want credentials stored in the MCP config.

```json
{
  "mcpServers": {
    "icedq": {
      "command": "npx",
      "args": ["-y", "@icedq/mcp-server"],
      "env": {
        "ICEDQ_BASE_URL": "https://app.icedq.net",
        "ICEDQ_REALM": "iam.icedq",
        "ICEDQ_CLIENT_ID": "<your-client-id>",
        "AUTH_TYPE": "device_flow",
        "ICEDQ_ORG_ID": "<your-org-id>",
        "NODE_OPTIONS": "--use-system-ca"
      }
    }
  }
}
```

On first run, the server prints a verification URL and code to the console and opens your browser automatically. Once you log in, tokens are cached (OS keychain, falling back to a token file) and silently refreshed on subsequent runs — no need to re-authenticate. Set `REMEMBER_ME=false` to skip the cache and force a fresh login every time. See the [Device Flow internals guide](docs/deployment/device-flow-auth.md) for details.

#### Alternative: Access Token Authentication (pre-issued tokens)

If you already have an OAuth access/refresh token pair (e.g. issued by your own automation or a prior login),