README.md
AI-native data analysis agent as an MCP Server.
lucid-skill
AI-native data analysis skill. Connect Excel, CSV, MySQL, PostgreSQL — understand business semantics, query with SQL.
No API key required. No LLM inside — the AI agent is the brain; lucid-skill is the hands.
Features
- Multi-source: Excel (.xlsx/.xls), CSV, MySQL, PostgreSQL — all unified into SQL
- Semantic Layer: Define business meanings for tables and columns; persist as YAML, Git-friendly
- JOIN Discovery: Automatically find join paths between tables (direct + indirect)
- Domain Clustering: Auto-group tables into business domains
- Embedding Search: Optional multilingual vector search for table discovery
- Read-only Safety: Only SELECT allowed — mutating SQL is blocked at the engine level
Install
pip install lucid-skill
# Or with uv (recommended for OpenClaw)
uv tool install lucid-skill
# Optional: database drivers
pip install "lucid-skill[db]" # MySQL + PostgreSQL
# Optional: embedding search
pip install "lucid-skill[embedding]" # sentence-transformers
Quick Start
# Connect a data source
lucid-skill connect csv /path/to/sales.csv
# Explore schema and semantics
lucid-skill init-semantic
# Search tables by business meaning
lucid-skill search "销售额 客户"
# Query with SQL
lucid-skill query "SELECT product, SUM(amount) FROM sales GROUP BY product ORDER BY 2 DESC LIMIT 10"
Architecture
Agent ──→ lucid-skill CLI ──→ Connectors (Excel/CSV/MySQL/PG)
│ │
├── Catalog (DuckDB) └── DuckDB (in-memory query engine)
└── Semantic Store (YAML)
- No LLM inside — lucid-skill provides data access; the AI agent handles reasoning
- DuckDB unified — catalog storage + query engine, single dependency, no compilation needed
- Semantic persistence — YAML definitions survive restarts, shareable via Git
Supported Data Sources
| Type | Format | Notes |
|---|---|---|
| Excel | .xlsx, .xls |
Multiple sheets supported |
| CSV | .csv |
Auto-detects encoding and delimiter |
| MySQL | 5.7+ / 8.0+ | Reads foreign keys and column comments (pip install lucid-skill[db]) |
| PostgreSQL | 12+ | Reads foreign keys and column comments (pip install lucid-skill[db]) |
Environment Variables
| Variable | Default | Description |
|---|---|---|
LUCID_DATA_DIR |
~/.lucid-skill/ |
Data directory (catalog, semantic store, models) |
LUCID_EMBEDDING_ENABLED |
false |
Enable vector search (~460 MB model download on first use) |
Security
- Read-only: Only
SELECT/WITHstatements are allowed; all mutating SQL is blocked - No credentials stored: Database passwords are never written to disk
- Local only: All data stays on your machine
MCP Server Mode
lucid-skill also works as an MCP Server for platforms that support it:
lucid-skill serve
Development
git clone https://github.com/WiseriaAI/lucid-skill
cd lucid-skill
pip install -e ".[dev]"
pytest
License
MIT
Environment Variables
LUCID_DATA_DIRData directory for catalog, semantic store, and modelsLUCID_EMBEDDING_ENABLEDEnable vector search for table discoveryConfiguration
claude_desktop_config.json
{"mcpServers": {"lucid-skill": {"command": "lucid-skill", "args": ["serve"]}}}Try it
→Connect to my sales.csv file and calculate the total revenue by product.
→Search for tables related to customer demographics and join them with my sales data.
→Query the MySQL database to find the top 10 customers by order volume.
→Explain the business semantics of the current data schema.