iceDQ MCP Server (io.github.icedq-tools/mcp-server)
The iceDQ MCP Server is an MCP Server for the iceDQ Data Reliability Platform. It provides a way to connect an AI assistant to the platform, with additional details available in the project documentation and support contacts listed by the repository.
🛠️ Key Features
MCP Server for iceDQ Data Reliability Platform
Repository-provided references to Website, Documentation, and Support
🚀 Use Cases
Connect an AI assistant to the iceDQ Data Reliability Platform
Use the linked documentation for integration guidance
⚡ Developer Benefits
Centralized entry points for integration via Documentation
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.
49 tools covering the full data quality lifecycle:
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.
Step 2 — Install via npm
The iceDQ MCP Server is published on npm as @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:
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) — 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.
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 for details.
If you already have an OAuth access/refresh token pair (e.g. issued by your own automation or a prior login), point the server at a token JSON file instead of supplying credentials directly:
The server reads this file on startup, uses the access token until it expires, and automatically refreshes it (rewriting the file) using the refresh token — no browser or password prompt involved. This is the recommended option for headless automation, CI, or server-to-server integrations where interactive login isn't possible.
Setup Guides
Choose your AI client for a step-by-step walkthrough:
The server ships eight skills under skills/ (also packaged into the Claude plugin). Each skill is
self-contained; shared references are edited in skills/_shared/ and copied with sync.sh.
Skill
Use when
icedq-suggest-checks
You want recommendations, coverage analysis, or a testing plan
icedq-author-rules
You already know the checks (or another skill handed over a rule spec)
icedq-compare-datasets
Migration certification or ongoing reconciliation between two datasets
icedq-mapping-doc-rules
Checks should be derived from a mapping document
icedq-etl-code-rules
Checks should be derived from ETL/SQL/dbt code
icedq-api-testing
The source is a named REST API (validation or recon against a backend)
icedq-run-and-report
Execute existing rules/workflows and read exception reports
icedq-schedule-and-monitor
Automate existing rules and inspect schedule history
See skills/COMPATIBILITY.md for the skill ↔ server version policy, and evals/README.md for the evaluation suite.
Complete Tool Reference
Full names, parameters, and category counts are in Tools References (49 tools). Summary:
Discovery & Exploration (11 tools)
Tool
Description
List Workspaces
List all workspaces in your iceDQ instance
List Connections
List data source connections in a workspace
Test Connection
Test connectivity for a data source connection
List Folders
List folders for organizing rules, workflows, schedules, and parameters
List Rules
Search and filter rules by folder, name, state, or type
List Workflows
List all workflows in a workspace
List Schedules
List all schedules in a workspace
Get Database Metadata
Get connection details and database capabilities
List Connection Metadata
Navigate databases, schemas, tables, or columns for a connection
Get Rule
Get full rule configuration, checks, and metadata
Get Guidance
Get step-by-step workflow guidance before starting a multi-step task
Data Analysis & Profiling (6 tools)
Tool
Description
Fetch Sample Data
Fetch real rows from a database table or custom SQL query
List Files
List files available in a flat-file connection (Azure Blob, S3, local)
Fetch File Sample Data
Fetch sample data from a file (CSV, Parquet, Excel, JSON, XML) and register its schema
Fetch API Sample Data
Fetch sample data from a REST API endpoint and register its schema
Profile Data
Analyze sample data for nulls, patterns, types, uniqueness
Suggest Quality Checks
AI-powered check recommendations from profiled data
Rule Creation (6 tools)
Tool
Description
Create Validation Rule
Row-level validation with NotNull, Format, ValidValues, Length, Date, and Custom checks
Create Duplicate Rule
Duplicate detection on single or composite columns
Create Pushdown Rule
SQL-driven aggregate and cross-table validation
Create Checksum Rule
Cross-source numeric comparison (COUNT, SUM, AVG)
Analyze Recon Mapping
AI-powered join key and column mapping suggestions
Create Recon Rule
Row-level cross-source reconciliation
Rule Management (3 tools)
Tool
Description
Update Rule
Add/remove checks, change source table or SQL
Move Rules or Workflows
Move rules or workflows between folders (batch supported, async)
Check Task Status
Monitor async operations such as moves
Custom Functions (3 tools)
Tool
Description
Manage Custom Function
Create or update a Java/Groovy UDF (Evaluator or Processor type)
List Custom Functions
List all UDFs in a workspace
Get Custom Function
Get the full source code and metadata of a UDF
Workflows (2 tools)
Tool
Description
Create Workflow
Chain multiple rules into a sequential workflow
Update Workflow Rules
Add or remove rules from an existing workflow
Schedules (3 tools)
Tool
Description
Create Schedule
Schedule automated rule/workflow execution
Modify Schedule
Update schedule timing, recurrence, or configuration
Add Rules/Workflows to Schedule
Add additional rules/workflows to an existing schedule
Parameters (4 tools)
Tool
Description
List Parameters
List and search parameters in a workspace
Get Parameter
Get full details of a parameter, including key-value pairs
Create or Update Parameter
Create a new parameter or update an existing one
Parse CSV and Create Parameter
Import a parameter's key-value pairs from a CSV file
Data Warehouse Queries (3 tools)
Tool
Description
Datawarehouse Query Schema
Discover datasets, columns, metrics, and joins available for querying
Datawarehouse Query Executor
Execute structured, schema-validated data warehouse queries
Validate and Explain Structured Query
Dry-run a query and preview generated SQL before executing
Execution & Monitoring (7 tools)
Tool
Description
Execute Rules or Workflows
Execute one or more rules or workflows on demand
Execute Schedule
Trigger a schedule on demand
Get Rule/Workflow Run History
View execution history for a rule or workflow
Get Workflow Run Status or Result
Track progress or fetch detailed per-activity results of an execution
Get Scheduler Runs History
View execution history for a schedule
Get Checks Exception Report
View row-level failure details for a rule run
Get Exception Report URL
Get the iceDQ UI URL to view the full exception report for a rule or workflow instance
Organization (1 tool)
Tool
Description
Create Folder
Create folders to organize rules, workflows, schedules, and parameters
Troubleshooting
Issue
Solution
Organization ID required
Add your Organization ID in configuration (e.g. org-icedq)
SSL certificate verification failed
Claude Desktop: uncheck Verify SSL. npx: set VERIFY_SSL to false (self-signed certs only). Prefer NODE_OPTIONS: --use-system-ca for corporate CAs
No workspaces returned
Verify credentials, check base URL, ensure user has workspace access
Sample data not returning
Check connection is ACTIVE, verify table name (case-sensitive), check permissions
Authentication failures
Verify client ID, client secret, username, and password are correct
Enable Debug Mode
For detailed troubleshooting, enable verbose logging:
Claude Desktop (extension): Settings → Extensions → iceDQ → Configure → Debug Mode: ON
npx / manual configuration: add "DEBUG": "true" to the env block of your MCP configuration
Claude Desktop extension log locations:
Windows:%APPDATA%\Claude\Logs\extensions\
macOS:~/Library/Logs/Claude/extensions/
Security & Privacy
How Your Data is Protected
Credentials are provided through your AI client's configuration and sent only to your iceDQ instance — the Claude Desktop extension stores them in your operating system keychain
All communication uses HTTPS with OAuth 2.0 authentication
Data flows directly between your AI client and your iceDQ instance -- no third parties
No telemetry or tracking of any kind
No data persistence by the MCP server beyond the active session, except tokens you opt into (device_flow OS keychain / access_tokenTOKENS_PATH)
SSL verification is enabled by default
Privacy Policy
Data collection: None. The MCP server collects no usage data, telemetry, or analytics.
Usage & storage: All data flows directly between your AI client and your iceDQ instance. The MCP server holds credentials and API tokens in memory for the active session. In device_flow mode, tokens are cached in the OS keychain (with a local file fallback). In access_token mode, tokens are persisted to the TOKENS_PATH file you supply. Nothing is written anywhere else.
Third-party sharing: None. No data is transmitted to Anthropic, iceDQ, or any third party beyond your own iceDQ instance.
Data retention: The MCP server retains nothing after the session ends. Token files (if used) remain on your local machine under your full control and can be deleted at any time.