# 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](https://hassanvfx.github.io/mcp-data-analysis-agent/).

## The two-stage workflow

| Once per machine | Once per data project folder |
| --- | --- |
| Install the executable and machine-local absolute MCP client entries. | Configure that folder’s private `.mcp-data-source`. |
| No database URL or credential is stored globally. | The file holds exactly one SQLite path/URL or PostgreSQL URL. |
| Reuse the MCP server across projects. | Run preflight, inspect schema, and analyze that project’s data. |

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

```bash
cd /path/to/data-project
```

Choose one project action:

| Tell your agent | Result |
| --- | --- |
| **Please configure this folder.** | Deterministically initializes `.mcp-data-agent/`, then creates or opens `.mcp-data-source` and runs preflight. |
| **Please install demo in this folder.** | Initializes the hidden workspace and creates the deterministic retail demo only in this folder. |
| **Please enable MCP Data Analysis for this Cline project.** | Activates Cline's visible runtime settings for this one project, then tells you to reload VS Code. |

The canonical commands are:

```bash
# 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:

```bash
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:

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

If you already cloned this checkout:

```bash
./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](https://hassanvfx.github.io/mcp-data-analysis-agent/).

### Cline in VS Code

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

```bash
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:

```bash
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](https://hassanvfx.github.io/mcp-data-analysis-agent/)
- [Operational reference](docs/OPERATIONS.md)
- [Security policy](docs/SECURITY.md)