Senzing MCP Server

Model Context Protocol (MCP) server for the Senzing SDK, providing entity resolution capabilities to Claude and other MCP clients.

Overview

This MCP server exposes Senzing SDK functionality through the Model Context Protocol, enabling AI assistants like Claude to:

• Search for entities by attributes
• Add and manage entity records
• Analyze relationships and networks
• Explain entity resolution decisions
• Perform bulk data imports with multithreading

Features

Entity Search & Retrieval

• search_entities: Search by name, address, phone, email, etc.
• get_entity: Retrieve detailed entity information by ID

Record Management

• add_record: Add single entity records
• add_records_from_file: Bulk import from JSONL files with multithreading
• delete_record: Remove records from the repository

Relationship Analysis

• find_relationship_path: Discover paths between entities
• find_network: Analyze networks of related entities
• explain_relationship: Understand why entities are related
• explain_entity_resolution: See how entities were resolved

Configuration & Diagnostics

• get_stats: View engine statistics and metrics
• get_config_info: Check configuration and version info

Installation

Prerequisites

• Python 3.10 or higher
• Senzing SDK v4beta installed at /data/etl/senzing/er/v4beta/sdk/python
• Senzing database configured and accessible

Setup

1. Clone or navigate to the project directory:

cd /data/etl/senzing/er/v4beta/senzingMCP

2. Install the package:

pip install -e .

3. Configure environment variables:

cp .env.example .env
# Edit .env with your Senzing configuration

Required environment variables:

• SENZING_ENGINE_CONFIGURATION_JSON: JSON string with database and resource paths

Optional environment variables:

• SENZING_MODULE_NAME: Module identifier (default: "senzing-mcp")
• SENZING_INSTANCE_NAME: Instance name (default: "senzing-mcp-server")
• SENZING_LOG_LEVEL: Verbosity level (default: 0)

Usage

Running the Server

Start the MCP server:

senzing-mcp

Or run directly:

python -m senzing_mcp.server

Configuration for AI Assistants

This MCP server can be used with multiple AI assistants:

• Claude Desktop: See installation instructions below
• ChatGPT Desktop: See CHATGPT_SETUP.md
• Amazon Q Developer: See AMAZON_Q_SETUP.md
• Remote Setup (Mac to Linux): See MAC_SETUP_INSTRUCTIONS.md

Claude Desktop Configuration

Add to your Claude Desktop MCP settings file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "senzing": {
      "command": "senzing-mcp",
      "env": {
        "SENZING_ENGINE_CONFIGURATION_JSON": "{\"PIPELINE\": {\"CONFIGPATH\": \"/etc/opt/senzing\", \"RESOURCEPATH\": \"/opt/senzing/g2/resources\", \"SUPPORTPATH\": \"/opt/senzing/data\"}, \"SQL\": {\"CONNECTION\": \"sqlite3://na:na@/var/opt/senzing/sqlite/G2C.db\"}}"
      }
    }
  }
}

Example Queries in Claude

Once configured, you can ask Claude:

Search for entities with the name "John Smith" and phone "555-1234"

Add a customer record with ID "CUST-001" containing name "Jane Doe" and email "jane@example.com"

Find the relationship path between entity 100 and entity 200

Import records from /path/to/customers.jsonl into the CUSTOMERS data source

Explain why entities 100 and 200 are related

File Format for Bulk Import

The add_records_from_file tool expects JSONL format (one JSON object per line):

{"RECORD_ID": "001", "NAME_FULL": "John Smith", "ADDR_FULL": "123 Main St", "PHONE_NUMBER": "555-1234"}
{"RECORD_ID": "002", "NAME_FULL": "Jane Doe", "EMAIL_ADDRESS": "jane@example.com", "DATE_OF_BIRTH": "1990-01-15"}
{"RECORD_ID": "003", "NAME_FULL": "Bob Johnson", "PHONE_NUMBER": "555-5678"}

Architecture

senzingMCP/
├── src/
│   └── senzing_mcp/
│       ├── server.py         # MCP server with tool definitions
│       └── sdk_wrapper.py    # Async wrapper for Senzing SDK
├── pyproject.toml            # Project configuration
├── .env.example              # Environment template
└── README.md                 # This file

Key Components

• server.py: MCP server implementation using the official mcp package

  • Defines 11 tools for entity resolution operations
  • Handles tool calls and routes to SDK wrapper
  • Uses stdio transport for Claude Desktop integration

• sdk_wrapper.py: Async wrapper for synchronous Senzing SDK

  • Initializes SDK from environment variables
  • Provides async interface using ThreadPoolExecutor
  • Handles error translation and bulk operations

Development

Running Tests

pytest tests/

Debugging

Set log level for more verbose output:

export SENZING_LOG_LEVEL=1
senzing-mcp

Common Issues

SDK Initialization Failed

• Check that SENZING_ENGINE_CONFIGURATION_JSON is properly formatted
• Verify database connection settings
• Ensure Senzing resources are accessible at specified paths

Import Path Issues

• Verify Senzing SDK is installed at /data/etl/senzing/er/v4beta/sdk/python
• Check that the path is accessible and contains the senzing module

Performance Issues with Bulk Import

• Adjust max_workers parameter (default: 5)
• Monitor system resources during large imports
• Consider breaking very large files into smaller batches

License

This MCP server implementation is provided as-is. Senzing SDK usage is subject to Senzing licensing terms.

Support

For issues with:

• MCP Server: Check server logs and environment configuration
• Senzing SDK: Consult Senzing documentation
• Claude Integration: Verify MCP configuration in Claude Desktop settings