MCP Data Analysis Agent

Safe, read-only SQLite and PostgreSQL analysis for coding agents.

Start with one instruction

Tell your agent:

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

It installs MCP Data Analysis once as a credential-free global MCP server. It does not create a database, configure a source, or change your current project.

Then open the full guide: Getting started and project configuration.

Related MCP server: sql-explorer-mcp

The two-stage workflow

Move into the separate folder containing the data you want to analyze before the next step.

cd /path/to/data-project

Choose one project action:

The canonical commands are:

# Real source: writes an ignored, mode-0600 .mcp-data-source file.
mcp-data-cli configure-source /absolute/path/to/analytics.sqlite --yes

# Or activate the deterministic retail demo for the current folder.
mcp-data-cli demo start --yes

# Confirm a bounded, read-only connection probe succeeds.
mcp-data-cli preflight

Supported databases and safety

• SQLite: an absolute local path or local SQLite URL.

• PostgreSQL: a postgres:// or postgresql:// URL using a dedicated database-level read-only account.

• Not supported: MySQL and other database dialects.

.mcp-data-source is the project’s runtime connection secret. Keep it regular (not a symlink), one line only, mode 0600, and out of version control. Global MCP configuration never contains a database URL or MCP_DATA_SOURCE_URL.

The first project-specific configure or demo action creates .mcp-data-agent/: its empty versioned workspace, schema cache, managed demo, and durable observability ledger. If you created .mcp-data-source manually, run mcp-data-cli prepare-workspace --yes before preflight. The project root must be writable; workspace_initialization_required tells you to prepare it, while PROJECT_STATE_UNAVAILABLE tells you to choose a writable regular folder. MCP never runs a query without its task and receipt evidence. Legacy root-level observability/ and .mcp-data/ locations are not read, migrated, or removed.

After preflight returns ready, ask the agent to inspect schema or run a bounded governed query. For the demo:

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

Installation commands

Public install:

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

If you already cloned this checkout:

./install.sh --local

The installer configures supported global client entries for Codex, Claude Code, Copilot, Cline, Cursor, Windsurf, and Continue. Each global entry uses the verified absolute path of this machine’s installed mcp-data-mcp, avoiding editor PATH issues while still containing no database secret. For complete client compatibility, demo cleanup, project-scoped fallback setup, Cline VS Code reload guidance, and operations details, use the hosted guide.

Cline in VS Code

Cline's visible MCP settings are global to the editor host, so activate one project explicitly after opening that folder:

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

This writes only the absolute MCP executable, --project-root, and .mcp-data-source to every detected Cline runtime file; it never writes a database URL or environment secret. Run Developer: Reload Window in VS Code, then open Cline → MCP Servers. Switching projects requires activation again. Use mcp-data-cli cline status to inspect the exact files and their managed state. .cline/mcp.json is a legacy project-local file and is not treated as Cline's active VS Code configuration.

Remove it from all agents

Tell your agent: “Please uninstall MCP Data Analysis from all agents.” It previews exact managed global entries and managed demos first. After you confirm the preview, it runs:

mcp-data-cli uninstall --all
mcp-data-cli uninstall --all --apply --yes

Add --project-root /absolute/path/to/project for every project-scoped fallback entry you also want removed. Cleanup never deletes custom sources, databases, governance files, observability evidence, or unrelated client settings.

More information

• Hosted getting-started guide

• Operational reference

• Security policy