# cdata-python-mcp-server
A generic Model Context Protocol (MCP) Server for CData Python Connectors. 

## Quick Start (Experienced Users)

```bash
# Clone and setup
git clone https://github.com/CDataSoftware/cdata-mcp-python.git
cd cdata-mcp-python
uv venv && uv pip install "mcp[cli]"

# Install your connector (from the project directory!)
uv pip install ./your-cdata-connector.whl

# Verify installation
uv pip list | grep cdata

# Test connection
export CONNECTOR_MOD="cdata.{datasource}"
export CONNECTION_STRING="InitiateOAuth=GETANDREFRESH;"  # Or your auth method
uv run python -c "from utils.get_connection import get_connection; print('✅ Connected!' if get_connection() else '❌ Failed')"

# Configure Claude Desktop (add to claude_desktop_config.json)
# Then restart Claude completely
```

## Purpose
We created this MCP Server to allow LLMs (like Claude) to query live data from any of over 250+ sources ([listed below](#supported-sources)) supported by [CData Python Connectors](https://www.cdata.com/python) ([free Community Licenses](https://www.cdata.com/developers/python/#pythonsources) for personal use).

CData Python Connectors connect to SaaS apps, NoSQL stores, and APIs by exposing them as relational SQL models.

This server wraps those connectors and makes their data available through a simple MCP interface, so LLMs can retrieve live information by asking natural language questions — no SQL required.

## Prerequisites

### System Requirements
- **Python**: 3.12 or higher
- **Operating System**: Windows, macOS, or Linux
- **Package Manager**: `uv` (for Python dependency management)

### Required Components

1. **UV Package Manager**

    Install with pip:
    ```bash
    pip install uv
    ```

2. **CData Python Connector**
    
    You'll need a CData Python Connector for your specific data source. The connector name format is `cdata.{datasource}` (e.g., `cdata.salesforce`, `cdata.jira`, `cdata.mongodb`).

    - **Download**: Visit [https://www.cdata.com/python/download/](https://www.cdata.com/python/download/)
    - **Select**: Choose your specific data source from the dropdown
    - **License**: Free 30-day trial or [Community License](https://www.cdata.com/developers/python/#pythonsources) available
    - **Note**: Save the downloaded wheel (.whl) or tarball (.tar.gz) file location

3. **Connection Configuration**
    
    Prepare your connection string with authentication details for your data source. Each connector has different requirements.

    <details>
    <summary><strong>Common Connection String Examples</strong></summary>

    - **Salesforce**: 
      ```
      # Full OAuth with domain
      InitiateOAuth=GETANDREFRESH;LoginURL=domain.my.salesforce.com;
      
      # Simplified OAuth (often works without LoginURL)
      InitiateOAuth=GETANDREFRESH;
      
      # Username/Password
      User=email@company.com;Password=yourpass;SecurityToken=token;LoginURL=domain.my.salesforce.com;
      ```
    
    - **MongoDB**:
      ```
      Server=localhost;Port=27017;Database=mydb;User=myuser;Password=mypass;
      ```
    
    - **MySQL**:
      ```
      Server=myserver.com;Port=3306;Database=mydb;UID=myuser;PWD=mypass;
      ```
    
    - **REST API**:
      ```
      Format=JSON;URI=https://api.example.com/data;AuthScheme=OAuth;
      ```

    Find your connector's specific requirements at: `https://cdn.cdata.com/help/{datasource}/pg_connectionprops.htm`
    </details>

## Setup Guide

### Step 1: Clone the Repository

```bash
git clone https://github.com/CDataSoftware/cdata-mcp-python.git
cd cdata-mcp-python
```

### Step 2: Set Up Python Environment

1. Create the virtual environment:
    ```bash
    uv venv
    ```
    
    > **Note**: With `uv`, you typically don't need to manually activate the virtual environment. The `uv pip` and `uv run` commands automatically use the `.venv` in the current directory.

2. Install MCP dependencies:
    ```bash
    uv pip install "mcp[cli]"
    ```
    
3. Verify the virtual environment is being used:
    ```bash
    uv pip list  # Should show it's using .venv in the current directory
    ```

### Step 3: Install Your CData Connector

Install the CData Python Connector you downloaded earlier:

**Windows:**
```bash
uv pip install "C:\path\to\cdata_{datasource}_connector-23.0.xxxx-cp312-cp312-win_amd64.whl"
```

**macOS/Linux:**
```bash
uv pip install /path/to/cdata-{datasource}-connector-23.0.xxxx-py3-none-any.whl
```

Example for Salesforce:
```bash
uv pip install ./cdata_salesforce_connector-23.0.8691-py3-none-any.whl
```

**Important**: Always run `uv pip` commands from the project directory to ensure packages are installed in the correct virtual environment. You can verify the installation with:
```bash
uv pip list | grep cdata
```

### Step 4: Activate Your Connector License

> **Note**: Some connectors may work without explicit license activation during initial testing. If you encounter license errors, follow the activation steps below.

<details>
<summary><strong>License Activation Instructions</strong></summary>

Locate and run the license installer for your connector:

1. Find the installer location using this Python script:
    ```python
    import os
    import cdata.{datasource}  # Replace {datasource} with your connector name
    path = os.path.dirname(os.path.abspath(cdata.{datasource}.__file__))
    print(f"License installer location: {path}/installlic_{datasource}/")
    ```

2. Navigate to the installer directory and activate:
    
    **Windows:**
    ```bash
    cd .venv\Lib\site-packages\cdata\installlic_{datasource}
    .\install-license.exe  # For trial license
    # OR
    .\install-license.exe YOUR-LICENSE-KEY  # For paid license
    ```
    
    **macOS/Linux:**
    ```bash
    cd .venv/lib/python3.12/site-packages/cdata/installlic_{datasource}
    ./install-license.sh  # For trial license
    # OR
    ./install-license.sh YOUR-LICENSE-KEY  # For paid license
    ```
</details>

## Testing Your Setup

<details>
<summary><strong>Testing Instructions</strong></summary>

### Step 1: Test Your Connector Installation

Before configuring Claude Desktop, verify your connector works correctly:

```python
# test_connector.py
import os
os.environ['CONNECTOR_MOD'] = 'cdata.{datasource}'  # Replace with your connector
os.environ['CONNECTION_STRING'] = 'Your=Connection;String=Here;'

try:
    from utils.get_connection import get_connection
    conn = get_connection()
    cursor = conn.cursor()
    cursor.execute("SELECT * FROM sys_tables")
    tables = cursor.fetchall()
    print(f"Successfully connected! Found {len(tables)} tables.")
    for table in tables[:5]:  # Show first 5 tables
        print(f"  - {table[0]}")
    cursor.close()
    conn.close()
except Exception as e:
    print(f"Connection failed: {e}")
```

Run the test:
```bash
python test_connector.py
```

### Step 2: Test the MCP Server

Run the server directly to ensure it starts without errors:

```bash
export CONNECTOR_MOD="cdata.{datasource}"  # Windows: set CONNECTOR_MOD=cdata.{datasource}
export CONNECTION_STRING="Your=Connection;String=Here;"  # Windows: set CONNECTION_STRING=...
uv run --active main.py
```

You should see:
```
Starting server
```

Press Ctrl+C to stop the server.
</details>

## Using the Server with Claude Desktop

### Step 1: Configure Claude Desktop

Create or edit the Claude Desktop configuration file:

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

Add your MCP server configuration:

```json
{
    "mcpServers": {
        "salesforce_server": {
            "command": "uv",
            "args": [
                "--directory",
                "/absolute/path/to/cdata-mcp-python",
                "run",
                "--active",
                "main.py"
            ],
            "env": {
                "CONNECTOR_MOD": "cdata.salesforce",
                "CONNECTION_STRING": "InitiateOAuth=GETANDREFRESH;LoginURL=mycompany.my.salesforce.com;"
            }
        }
    }
}
```

**Important Notes:**
- Replace `salesforce_server` with a descriptive name for your data source
- Use the absolute path to your cloned repository directory
- Replace `cdata.salesforce` with your actual connector module name
- Use your actual connection string (keep it secure!)

### Step 2: Restart Claude Desktop

1. **Fully quit Claude Desktop** (not just close the window):
   - Windows: Right-click system tray icon → Quit
   - macOS: Claude → Quit Claude (Cmd+Q)
   - Linux: Close and ensure process is terminated

2. **Reopen Claude Desktop**

3. **Verify the server appears** in the MCP servers list (look for the server icon)

### Step 3: Test with Claude

Ask Claude questions about your data:
- "What tables are available in my Salesforce instance?"
- "Show me the first 5 records from the Account table"
- "What fields are in the Contact table?"

## Usage Details
Once the MCP Server is configured, the AI client will be able to use the built-in tools to read, write, update, and delete the underlying data. In general, you do not need to call the tools explicitly. Simply ask the client to answer questions about the underlying data system. For example:
* "What is the correlation between my closed won opportunities and the account industry?"
* "How many open tickets do I have in the SUPPORT project?"
* "Can you tell me what calendar events I have today?"

The list of tools available and their descriptions follow:
## Available Tools

The MCP server provides these tools to Claude for interacting with your data:

| Tool | Description | Example Use |
|------|-------------|-------------|
| `get_tables` | Lists all available tables/views | "What tables are available?" |
| `get_columns` | Shows fields for a specific table | "What fields are in the Account table?" |
| `get_procedures` | Lists available stored procedures | "What actions can I perform?" |
| `get_procedure_params` | Shows parameters for a procedure | "What parameters does CreateInvoice need?" |
| `run_query` | Executes SELECT queries | "Show me all contacts from California" |
| `run_nonquery` | Executes INSERT/UPDATE/DELETE | "Update the phone number for contact ID 123" |
| `call_procedure` | Calls stored procedures | "Execute the RefreshToken procedure" |

## Troubleshooting

<details>
<summary><strong>Common Issues and Solutions</strong></summary>

### MCP Server Not Appearing in Claude Desktop
**Problem:** The server doesn't show up in Claude's MCP servers list.

**Solutions:**
1. **Fully quit Claude Desktop** (not just minimize):
   - Windows: Check Task Manager and end all Claude processes
   - macOS: Use Activity Monitor to ensure Claude is not running
   - Linux: Use `ps aux | grep -i claude` to check for running processes

2. **Verify configuration file**:
   ```bash
   # Check if config file exists and is valid JSON
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python -m json.tool
   ```

3. **Check for syntax errors** in your configuration (missing commas, quotes, etc.)

### Connection Errors
**Problem:** "Connection failed" or authentication errors.

**Solutions:**
1. **Test connection string** using the test script provided in the Testing section
2. **Verify credentials** and authentication method for your data source
3. **Check network access** to your data source (VPN, firewall, etc.)
4. **OAuth connections**: Ensure redirect URLs are properly configured

### License Activation Issues
**Problem:** "License not found" or "Invalid license" errors.

**Solutions:**
1. **Verify license installation**:
   ```python
   import cdata.{datasource}
   print(cdata.{datasource}.__version__)  # Should show version if properly licensed
   ```

2. **Re-run license installer** with correct permissions (may need sudo on Linux/Mac)

3. **Check license expiration** for trial licenses (30 days)

### Module Import Errors
**Problem:** "ModuleNotFoundError: No module named 'cdata.{datasource}'"

**Solutions:**
1. **Ensure virtual environment is activated**:
   ```bash
   which python  # Should show .venv/bin/python path
   ```

2. **Reinstall connector** in the virtual environment:
   ```bash
   uv pip install --force-reinstall /path/to/connector.whl
   ```

3. **Verify CONNECTOR_MOD** environment variable matches installed module name

### Performance Issues
**Problem:** Queries are slow or timing out.

**Solutions:**
1. **Limit query results**:
   ```sql
   SELECT TOP 100 * FROM TableName  -- SQL Server syntax
   SELECT * FROM TableName LIMIT 100  -- MySQL/PostgreSQL syntax
   ```

2. **Add query filters** to reduce data transfer
3. **Check data source performance** directly
4. **Increase timeout values** in connection string if supported
</details>

<details>
<summary><strong>Debug Mode</strong></summary>

Enable verbose logging to diagnose issues:

1. Create a debug wrapper script:
   ```python
   # debug_server.py
   import os
   import sys
   import logging
   
   logging.basicConfig(level=logging.DEBUG, 
                      format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
   
   # Import and run your main server
   from main import *
   ```

2. Run with debug output:
   ```bash
   uv run --active debug_server.py
   ```
</details>

<details>
<summary><strong>Success Indicators</strong></summary>

Know when each step is working correctly:

### After Connector Installation
```bash
uv pip list | grep cdata
# ✅ Should show: cdata-{datasource}-connector
```

### After Connection Test
```python
# ✅ Successful connection shows:
Successfully connected! Found X tables.
  - TableName1
  - TableName2
  ...
```

### After Server Test
```bash
uv run --active main.py
# ✅ Should show: Starting server
# (Server will wait for connections - this is normal)
```

### In Claude Desktop
- ✅ Small plug icon appears next to your server name
- ✅ First query returns data without errors
- ✅ Example: "What tables are available?" returns a list
</details>

### Getting Help

If you're still having issues:

1. **Check connector documentation**: `https://cdn.cdata.com/help/{datasource}/`
2. **Join CData Community**: [https://community.cdata.com](https://community.cdata.com)
3. **Report MCP server issues**: Create an issue in this repository
4. **Contact CData support**: For connector-specific problems

## License
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the [LICENSE](./LICENSE) file in the project repository.

## Supported Sources

<details>
<summary><strong>250+ Supported Data Sources</strong></summary>

<table>
<tr><td>Access</td><td>Act CRM</td><td>Act-On</td><td>Active Directory</td></tr>
<tr><td>ActiveCampaign</td><td>Acumatica</td><td>Adobe Analytics</td><td>Adobe Commerce</td></tr>
<tr><td>ADP</td><td>Airtable</td><td>AlloyDB</td><td>Amazon Athena</td></tr>
<tr><td>Amazon DynamoDB</td><td>Amazon Marketplace</td><td>Amazon S3</td><td>Asana</td></tr>
<tr><td>Authorize.Net</td><td>Avalara AvaTax</td><td>Avro</td><td>Azure Active Directory</td></tr>
<tr><td>Azure Analysis Services</td><td>Azure Data Catalog</td><td>Azure Data Lake Storage</td><td>Azure DevOps</td></tr>
<tr><td>Azure Synapse</td><td>Azure Table</td><td>Basecamp</td><td>BigCommerce</td></tr>
<tr><td>BigQuery</td><td>Bing Ads</td><td>Bing Search</td><td>Bitbucket</td></tr>
<tr><td>Blackbaud FE NXT</td><td>Box</td><td>Bullhorn CRM</td><td>Cassandra</td></tr>
<tr><td>Certinia</td><td>Cloudant</td><td>CockroachDB</td><td>Confluence</td></tr>
<tr><td>Cosmos DB</td><td>Couchbase</td><td>CouchDB</td><td>CSV</td></tr>
<tr><td>Cvent</td><td>Databricks</td><td>DB2</td><td>DocuSign</td></tr>
<tr><td>Dropbox</td><td>Dynamics 365</td><td>Dynamics 365 Business Central</td><td>Dynamics CRM</td></tr>
<tr><td>Dynamics GP</td><td>Dynamics NAV</td><td>eBay</td><td>eBay Analytics</td></tr>
<tr><td>Elasticsearch</td><td>Email</td><td>EnterpriseDB</td><td>Epicor Kinetic</td></tr>
<tr><td>Exact Online</td><td>Excel</td><td>Excel Online</td><td>Facebook</td></tr>
<tr><td>Facebook Ads</td><td>FHIR</td><td>Freshdesk</td><td>FTP</td></tr>
<tr><td>GitHub</td><td>Gmail</td><td>Google Ad Manager</td><td>Google Ads</td></tr>
<tr><td>Google Analytics</td><td>Google Calendar</td><td>Google Campaign Manager 360</td><td>Google Cloud Storage</td></tr>
<tr><td>Google Contacts</td><td>Google Data Catalog</td><td>Google Directory</td><td>Google Drive</td></tr>
<tr><td>Google Search</td><td>Google Sheets</td><td>Google Spanner</td><td>GraphQL</td></tr>
<tr><td>Greenhouse</td><td>Greenplum</td><td>HarperDB</td><td>HBase</td></tr>
<tr><td>HCL Domino</td><td>HDFS</td><td>Highrise</td><td>Hive</td></tr>
<tr><td>HubDB</td><td>HubSpot</td><td>IBM Cloud Data Engine</td><td>IBM Cloud Object Storage</td></tr>
<tr><td>IBM Informix</td><td>Impala</td><td>Instagram</td><td>JDBC-ODBC Bridge</td></tr>
<tr><td>Jira</td><td>Jira Assets</td><td>Jira Service Management</td><td>JSON</td></tr>
<tr><td>Kafka</td><td>Kintone</td><td>LDAP</td><td>LinkedIn</td></tr>
<tr><td>LinkedIn Ads</td><td>MailChimp</td><td>MariaDB</td><td>Marketo</td></tr>
<tr><td>MarkLogic</td><td>Microsoft Dataverse</td><td>Microsoft Entra ID</td><td>Microsoft Exchange</td></tr>
<tr><td>Microsoft OneDrive</td><td>Microsoft Planner</td><td>Microsoft Project</td><td>Microsoft Teams</td></tr>
<tr><td>Monday.com</td><td>MongoDB</td><td>MYOB AccountRight</td><td>MySQL</td></tr>
<tr><td>nCino</td><td>Neo4J</td><td>NetSuite</td><td>OData</td></tr>
<tr><td>Odoo</td><td>Office 365</td><td>Okta</td><td>OneNote</td></tr>
<tr><td>Oracle</td><td>Oracle Eloqua</td><td>Oracle Financials Cloud</td><td>Oracle HCM Cloud</td></tr>
<tr><td>Oracle Sales</td><td>Oracle SCM</td><td>Oracle Service Cloud</td><td>Outreach.io</td></tr>
<tr><td>Parquet</td><td>Paylocity</td><td>PayPal</td><td>Phoenix</td></tr>
<tr><td>PingOne</td><td>Pinterest</td><td>Pipedrive</td><td>PostgreSQL</td></tr>
<tr><td>Power BI XMLA</td><td>Presto</td><td>Quickbase</td><td>QuickBooks</td></tr>
<tr><td>QuickBooks Online</td><td>QuickBooks Time</td><td>Raisers Edge NXT</td><td>Reckon</td></tr>
<tr><td>Reckon Accounts Hosted</td><td>Redis</td><td>Redshift</td><td>REST</td></tr>
<tr><td>RSS</td><td>Sage 200</td><td>Sage 300</td><td>Sage 50 UK</td></tr>
<tr><td>Sage Cloud Accounting</td><td>Sage Intacct</td><td>Salesforce</td><td>Salesforce Data Cloud</td></tr>
<tr><td>Salesforce Financial Service Cloud</td><td>Salesforce Marketing</td><td>Salesforce Marketing Cloud Account Engagement</td><td>Salesforce Pardot</td></tr>
<tr><td>Salesloft</td><td>SAP</td><td>SAP Ariba Procurement</td><td>SAP Ariba Source</td></tr>
<tr><td>SAP Business One</td><td>SAP BusinessObjects BI</td><td>SAP ByDesign</td><td>SAP Concur</td></tr>
<tr><td>SAP Fieldglass</td><td>SAP HANA</td><td>SAP HANA XS Advanced</td><td>SAP Hybris C4C</td></tr>
<tr><td>SAP Netweaver Gateway</td><td>SAP SuccessFactors</td><td>SAS Data Sets</td><td>SAS xpt</td></tr>
<tr><td>SendGrid</td><td>ServiceNow</td><td>SFTP</td><td>SharePoint</td></tr>
<tr><td>SharePoint Excel Services</td><td>ShipStation</td><td>Shopify</td><td>SingleStore</td></tr>
<tr><td>Slack</td><td>Smartsheet</td><td>Snapchat Ads</td><td>Snowflake</td></tr>
<tr><td>Spark</td><td>Splunk</td><td>SQL Analysis Services</td><td>SQL Server</td></tr>
<tr><td>Square</td><td>Stripe</td><td>Sugar CRM</td><td>SuiteCRM</td></tr>
<tr><td>SurveyMonkey</td><td>Sybase</td><td>Sybase IQ</td><td>Tableau CRM Analytics</td></tr>
<tr><td>Tally</td><td>TaxJar</td><td>Teradata</td><td>Tier1</td></tr>
<tr><td>TigerGraph</td><td>Trello</td><td>Trino</td><td>Twilio</td></tr>
<tr><td>Twitter</td><td>Twitter Ads</td><td>Veeva CRM</td><td>Veeva Vault</td></tr>
<tr><td>Wave Financial</td><td>WooCommerce</td><td>WordPress</td><td>Workday</td></tr>
<tr><td>xBase</td><td>Xero</td><td>XML</td><td>YouTube Analytics</td></tr>
<tr><td>Zendesk</td><td>Zoho Books</td><td>Zoho Creator</td><td>Zoho CRM</td></tr>
<tr><td>Zoho Inventory</td><td>Zoho Projects</td><td>Zuora</td><td>... Dozens More</td></tr>
</table>
</details>