<p align="center"> <img src="assets/logo.png" alt="LocalData MCP Server" width="250"> </p>

LocalData MCP Server

<!-- mcp-name: io.github.chrisgve/localdata-mcp -->

LocalData MCP gives LLM agents access to local and remote data — databases, files, graphs, and structured documents — along with a full data science toolkit for analysis and modeling. It exposes 70 MCP tools across 13 database types and 20+ file formats, with memory-bounded streaming so agents can work safely on large datasets without exceeding available RAM.

Quick Start

# Install permanently
uv tool install localdata-mcp

# Or run directly without installing
uvx localdata-mcp

First-run note: Data science dependencies (scipy, scikit-learn, statsmodels, geopandas) total around 200 MB and are downloaded on first use. Subsequent starts reuse the cache. If your MCP client times out on the first launch, reconnect — the next start will be immediate.

Add to your MCP client configuration:

{
  "mcpServers": {
    "localdata": {
      "command": "localdata-mcp"
    }
  }
}

For uvx (no permanent install):

{
  "mcpServers": {
    "localdata": {
      "command": "uvx",
      "args": ["localdata-mcp"]
    }
  }
}

Then connect to any supported source and start querying:

connect_database("sales", "postgresql", "postgresql://user:pass@localhost/db")
execute_query("sales", "SELECT product, SUM(amount) FROM orders GROUP BY product")

connect_database("records", "csv", "./records.csv")
analyze_hypothesis_test("records", "SELECT amount, region FROM data_table", column="amount", group_column="region")

A single-table file — CSV, TSV, JSON, XML, INI, Parquet, Feather, Arrow — is loaded into one table named data_table, whatever the connection is called. Run describe_database(name) after connecting if you are unsure what a source exposes; multi-sheet spreadsheets and databases keep their own table names.

Feature Overview

Core Database (8 tools)

Connect, query, and inspect databases and files. All queries execute within configurable memory limits (default 2 GB) with automatic chunked streaming for large result sets.

Streaming and Memory (9 tools)

Tree / Structured Data (10 tools)

Navigate and edit TOML, JSON, and YAML files as navigable trees. Supports full CRUD with auto-creation of ancestor nodes and round-trip export to any supported format.

Graph (7 tools)

Work with DOT, GML, GraphML, and Mermaid files as directed multigraphs. Supports full CRUD on nodes and edges, shortest-path and all-paths queries, structural statistics, and multi-format export.

Node-level operations reuse the tree tools above: get_node, set_node, delete_node, list_keys, get_value, set_value, and delete_key detect a graph connection and treat their path argument as a node ID. get_children and move_node are tree-only.

Search and Transform (2 tools)

Schema and Audit (3 tools)

System (2 tools)

Data Science (12 tools)

Run statistical analysis, modeling, and pattern detection directly on query results from any connected source.

Supported Data Sources

Databases

File Formats

Multi-sheet spreadsheets are supported: each sheet becomes a separately queryable table. To load one sheet only, pass its name as the fourth argument to connect_database — connect_database("q1", "excel", "./report.xlsx", "Q1 Results"). Use "excel" for both .xlsx and .xls; "xlsx" is not a connection type.

Data Science Domains

Statistical Analysis — t-tests, chi-squared, Mann-Whitney, Kruskal-Wallis, and related hypothesis tests; one-way ANOVA with post-hoc tests; Cohen's d, eta-squared, and other effect size measures.

Regression and Modeling — linear, polynomial, logistic, ridge, lasso, and elastic net regression; model evaluation with R², RMSE, MAE, and classification metrics; automated feature selection.

Pattern Recognition — K-means, DBSCAN, and hierarchical clustering; anomaly detection via isolation forest, LOF, and one-class SVM; dimensionality reduction with PCA, t-SNE, and UMAP.

Time Series — decomposition, stationarity testing, autocorrelation analysis; ARIMA and ETS forecasting; change point detection; multivariate analysis with VAR, Granger causality, and cointegration tests. forecast_time_series accepts method="arima" or method="ets"; the SARIMA and ensemble models in the domain package are not reachable through an MCP tool.

Business Intelligence — A/B test statistical analysis; RFM customer segmentation; cohort analysis, CLV modeling, and funnel analysis.

Geospatial — distance and coordinate calculations, spatial joins, interpolation, and network analysis.

Optimization — linear programming, constrained optimization, assignment problems, and network optimization.

Sampling and Estimation — bootstrap confidence intervals, Bayesian estimation, Monte Carlo simulation, and stratified sampling.

Claude Code plugin

The repository doubles as a Claude Code plugin. Its manifest (.claude-plugin/plugin.json) registers the localdata MCP server via uvx localdata-mcp and ships 18 skills and 11 agents that drive the tools above. See the plugin page for how to install it and how to invoke a skill.

Upgrading from 2.0.0: graph-explore is now graph-data-explore and graph-analyst is now graph-data-analyst, and every skill moved one directory deeper. Invoking an old name silently does nothing — the changelog lists the steps.

Skills are grouped by domain under skills/:

Agents in agents/ take on longer analyses that span several tools:

Architecture

• One uniform call shape — every analysis tool takes a connection name, a SQL query, and the column names it should work on. There is no separate load step and no data-frame argument: the query is the data selection, so the same call works against a CSV file and a PostgreSQL table
• Named methods, sensible defaults — the statistical procedure is chosen by name (method="dbscan", test_type="ttest_ind") and every method parameter has a default, so a call that names only the columns still runs. Thresholds such as alpha and contamination are numeric parameters, not inferred from intent
• Streaming-first execution — query results are chunked and buffered rather than materialized whole. execute_query returns the first chunk plus a query_id, and next_chunk walks the rest, so a result larger than the configured memory ceiling (default 2 GB) is still workable
• Self-describing query results — execute_query returns row counts, memory state, data-quality signals, and ready-to-run next_chunk calls alongside the rows, so an agent can decide what to do next without a second round trip

Configuration

LocalData MCP reads settings from a YAML config file, from environment variables, or from both; environment variables win. The defaults work for most cases. The most frequently changed variables:

Set them in your MCP server configuration under "env", or in a .env file in the working directory. The full set — staging, memory budget, disk budget, per-database LOCALDATA_DB_<NAME>_* definitions — is documented in the configuration reference.

Documentation

• Getting started — install, configure an MCP client, run the first queries
• Claude Code plugin — install the plugin, invoke a skill, what each skill and agent does
• Tools reference — every tool with parameters, return shape, and composition hints
• Configuration reference — config file discovery, every environment variable, every default
• Data sources — connection strings and quirks per database and file format
• Data science domains — what each of the eight analytical domains does
• Error classification — structured error types, retryability, and suggested recovery
• Docker usage — container deployment and configuration
• Troubleshooting — common failures and their fixes
• Rendered documentation — the same pages, searchable

Development

git clone https://github.com/ChrisGVE/localdata-mcp.git
cd localdata-mcp
uv sync --all-extras
uv run pytest tests/ --ignore=tests/integration

That command collects 2,312 unit tests. A further 357 integration tests live under tests/integration/ and need live database services — start them with docker-compose up -d, then run uv run pytest tests/integration/. The enterprise-scale suite inside that set loads 100K rows into each of 7 database engines and is by far the slowest part.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before submitting a pull request.

License

Apache License 2.0 — see LICENSE for details.