mcp-data-source

mcp-data-source

Multi-datasource MCP Server — connect AI assistants to 6 database types with dynamic configuration and secure credential storage.

📖 完整中文文档：docs/user-guide.md

Features

Architecture

MCP Client (Claude Code / Claude Desktop / OpenCode)
    │ stdio
    ▼
┌─────────────────────────────────────┐
│         mcp-data-source             │
│  ┌──────────┐  ┌──────────────────┐ │
│  │ 9 Tools  │  │  Connectors (6)  │ │
│  │ config/* │  │ mysql / pg / dws │ │
│  │ query/*  │  │ ch / mongo / sql │ │
│  └──────────┘  └──────────────────┘ │
│         │              │             │
│    ~/.mcp-data-source/   Remote DBs  │
│    config.db (encrypted)            │
└─────────────────────────────────────┘

Installation

cd mcp-data-source
npm install
npm run build
npm link            # makes mcp-ds globally available

Or for distribution:

npm pack            # → mcp-data-source-1.0.0.tgz
npm install -g mcp-data-source-1.0.0.tgz

Requirements: Node.js ≥ 18.x, npm ≥ 9.x.

MCP Client Configuration

Configuration is a two-step process: ① Set encryption key (system env var) → ② Register the server (MCP client config).

⚠️ MCP_DATA_SOURCE_KEY is a system environment variable read via process.env. It does NOT go in the MCP config file. The config only carries MCP_LOG_LEVEL (optional).

Step 1: Set Encryption Key (system env var)

First, generate and set MCP_DATA_SOURCE_KEY as a system environment variable (see Generate Encryption Key below).

macOS / Linux — add to ~/.zshrc or ~/.bashrc:

export MCP_DATA_SOURCE_KEY=your-64-char-hex-key

Windows — set in System Environment Variables, or PowerShell:

[Environment]::SetEnvironmentVariable("MCP_DATA_SOURCE_KEY", "your-64-char-hex-key", "User")

Restart your terminal / MCP client after setting.

Step 2: MCP Client Config

⚠️ Configuration format differs between MCP clients. Copy-pasting between them won't work.

Format Comparison

Claude Code

{
  "mcpServers": {
    "data-source": {
      "command": "mcp-data-source",
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Claude Desktop

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

{
  "mcpServers": {
    "data-source": {
      "command": "node",
      "args": ["/absolute/path/to/dist/server.js"],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

OpenCode

Config file: opencode.json in project root (not .mcp.json).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "data-source": {
      "type": "local",
      "command": ["mcp-data-source"],
      "environment": {
        "MCP_LOG_LEVEL": "info"
      },
      "enabled": true
    }
  }
}

Common OpenCode pitfalls: using mcpServers instead of mcp, env instead of environment, or forgetting "enabled": true.

CLI Tool (mcp-ds)

Manage data sources offline — passwords never go through the LLM.

# Add a data source (interactive password prompt — secure)
mcp-ds add mysql --name prod --host 10.0.0.1 --port 3306 --username admin --password

# Add via environment variable (for scripting)
DB_PASS=xxx mcp-ds add mysql --name prod --host 10.0.0.1 --username admin --password-env DB_PASS

# SQLite
mcp-ds add sqlite --name local --file-path /path/to/database.db

# ClickHouse with HTTPS
mcp-ds add clickhouse --name ch --host 10.0.0.1 --username admin --password --protocol https

# List, test, delete
mcp-ds list
mcp-ds test prod
mcp-ds delete prod

Full add Options

Generate Encryption Key

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# Or: openssl rand -hex 32

Set the generated key as a system environment variable (not in MCP config):

macOS/Linux: export MCP_DATA_SOURCE_KEY=... in ~/.zshrc or ~/.bashrcWindows: System Environment Variables, or [Environment]::SetEnvironmentVariable("MCP_DATA_SOURCE_KEY", "...", "User") in PowerShell

Keep it safe — if lost, stored passwords cannot be decrypted. Restart your MCP client after setting.

Supported Databases

MCP Tools Overview

Configuration (6 tools)

Query (3 tools)

Quick Usage Examples

# Add and explore
User: Add a MySQL data source named "prod" at 10.0.0.1:3306, user admin, password secret123
User: Test the connection
User: Show me the tables in prod

# Natural language query
User: How many orders were placed last month in the analytics database?
→ AI auto-discovers schema, constructs SQL, and returns results

# Pagination
User: Query users table, 50 per page
User: Next page

# Write operations (requires explicit authorization)
User: Insert a new user record, allow writes

Environment Variables

MCP_DATA_SOURCE_KEY is read from the system environment by process.env. MCP_LOG_LEVEL can be injected via the MCP client config.

Security

• AES-256-GCM authenticated encryption with random IV per operation
• Passwords stored encrypted in ~/.mcp-data-source/config.db
• list_data_sources never returns password fields
• Default readOnly: true blocks all write operations
• Each query uses an isolated connection, closed immediately after use
• Connection pooling (max 10) with automatic cleanup for MySQL/PostgreSQL

Troubleshooting

For detailed troubleshooting and advanced usage, see docs/user-guide.md.

License

MIT