MCP Data Analysis Agent — Getting started

Tell your agent

1. Install

Please install from https://github.com/hassanvfx/mcp-data-analysis-agent.

Installs the package and credential-free global MCP entries using this machine’s absolute executable path. It never creates a database or source file.

2. Configure a project

Please configure this folder.

Deterministically initializes the hidden workspace in the separate folder containing the data you intend to analyze.

3. Try the demo

Please install demo in this folder.

Initializes the workspace and creates the deterministic retail demo only in the current project folder.

Cline in VS Code

Please enable MCP Data Analysis for this Cline project.

Activates Cline's visible runtime settings for the open project and then asks you to reload VS Code.

The two-stage model

Install once per machine	Enable once per project folder
Installs `mcp-data-mcp` and credential-free client entries.	Creates an ignored `.mcp-data-source` containing that project’s connection location.
No database URLs, passwords, demos, or policy are global.	Run preflight, schema discovery, queries, and optional policy setup from this folder.

Global client entries use this machine’s verified absolute mcp-data-mcp path plus --source-file .mcp-data-source, avoiding editor PATH issues. When you switch projects, the server resolves the source file in the active project folder. Each project remains independent.

Install the global server

Ask your agent with the install prompt above, or run one of these commands yourself:

# Public package installation
curl -fsSL https://raw.githubusercontent.com/hassanvfx/mcp-data-analysis-agent/main/install.sh | bash

# Editable installation from an existing clone
./install.sh --local

The installer detects and merges exact, credential-free entries for Codex, Claude Code, Copilot, Cline, Cursor, Windsurf, and Continue. Restart or trust your client if it requests it.

Enable a specific project

First move to a folder that represents the project you want to analyze. Installation does not enable every folder automatically.

cd /path/to/data-project
mcp-data-cli configure-source /absolute/path/to/analytics.sqlite --yes
mcp-data-cli preflight

For PostgreSQL, configure a dedicated read-only account:

mcp-data-cli configure-source 'postgresql://readonly_user:password@db.example:5432/analytics' --yes
mcp-data-cli preflight

configure-source deterministically initializes .mcp-data-agent/, writes .mcp-data-source with mode 0600, and safely offers Git protection for private demo/cache assets. It never stores the value in global MCP configuration. If you create the source file yourself, run mcp-data-cli prepare-workspace --yes before preflight.

Manual configuration

Ask “Please configure this folder” to have your agent create or open the empty file in your normal text editor. Paste exactly one value, save, then run preflight. The file must be a regular non-symlink file containing one absolute SQLite path/local URL or PostgreSQL URL. Never commit it.

Confirm readiness

Preflight makes a short, bounded, read-only connection and runs SELECT 1; it does not create evidence, caches, artifacts, or data.

Status	Meaning and next action
`source_configuration_required`	No source file yet. Configure this folder or install the demo.
`source_configuration_invalid`	The source file or policy is malformed or unsafe. Correct the local configuration.
`source_unavailable`	The configured source failed a read-only probe. Check the path, network, and permissions.
`ready`	The read-only probe succeeded. Inspect schema or analyze data.

Try the deterministic retail demo

Use the demo before connecting real data. It is an explicit, confirmation-gated action in the current project only.

mcp-data-cli demo start --yes
mcp-data-cli preflight
mcp-data-cli schema data
mcp-data-cli query data 'SELECT id, name, stock FROM products ORDER BY id' --limit 10

This creates .mcp-data-agent/playground.sqlite, points .mcp-data-source to it, and creates governed observability evidence under .mcp-data-agent/observability/ after a query. To remove it safely, use mcp-data-cli demo stop --yes; it refuses to delete a custom source.

Inspect and analyze

# Discover tables and columns
mcp-data-cli schema data

# A bounded governed query
mcp-data-cli query data 'SELECT id, name FROM products ORDER BY id' --limit 2

The agent accepts read-only SELECT and WITH queries and rejects mutations, DDL, unsafe functions, attachments, multi-statements, and policy-restricted fields. PostgreSQL still needs database-level least-privilege permissions.

Supported databases

SQLite: an absolute local filesystem path or a local SQLite URL.
PostgreSQL: postgres:// or postgresql:// using a dedicated read-only database account.
Not supported at runtime: MySQL and other database dialects.

When a client does not use the project folder

Global setup depends on the client launching the MCP server from the active project directory. If that is not true for your client, run this from the data project to create a static project fallback:

mcp-data-cli setup --client <client> --apply

The fallback adds a validated --project-root, never a URL or credential. Cline uses a separate explicit activation because its visible editor settings are global to a host:

mcp-data-cli cline activate --project-root /absolute/path/to/data-project
mcp-data-cli cline activate --project-root /absolute/path/to/data-project --apply --yes
mcp-data-cli cline status

Activation synchronizes detected Cline runtime files for VS Code, VS Code Insiders, Cursor, Windsurf, native Cline, and historical Cline settings. It stores only the absolute executable and project root—never a source URL or secret. Run Developer: Reload Window afterwards; activate again when switching projects. The legacy .cline/mcp.json is not an active VS Code Cline setting.

Optional project governance and cleanup

Tell your agent: “Please uninstall MCP Data Analysis from all agents.” It previews exact managed cleanup first and applies only after your confirmation.

# After a successful preflight, create non-secret starter governance files.
mcp-data-cli configure-policy --yes

# Preview complete managed-client/demo cleanup.
mcp-data-cli uninstall --all --project-root /absolute/path/to/data-project

# Apply after review; repeat --project-root for every project fallback.
mcp-data-cli uninstall --all --project-root /absolute/path/to/data-project --apply --yes

Policy setup never infers rules from data or overwrites existing governance files. Cleanup preserves custom sources, databases, policy/catalog/recipe files, observability evidence, and unrelated client settings.