databeak 0.1.1

DataBeak: MCP server for comprehensive CSV file operations with pandas-based tools

DataBeak

AI-Powered CSV Processing via Model Context Protocol

Transform how AI assistants work with CSV data. DataBeak provides 40+ specialized tools for data manipulation, analysis, and validation through the Model Context Protocol (MCP).

Features

• 🔄 Complete Data Operations - Load, transform, analyze, and export CSV data
• 📊 Advanced Analytics - Statistics, correlations, outlier detection, data profiling
• ✅ Data Validation - Schema validation, quality scoring, anomaly detection
• 🎯 Stateless Design - Clean MCP architecture with external context management
• ⚡ High Performance - Handles large datasets with streaming and chunking
• 🔒 Session Management - Multi-user support with isolated sessions
• 🌟 Code Quality - Zero ruff violations, 100% mypy compliance, perfect MCP documentation standards, comprehensive test coverage

Getting Started

The fastest way to use DataBeak is with uvx (no installation required):

For Claude Desktop

Add this to your MCP Settings file:

{
  "mcpServers": {
    "databeak": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jonpspri/databeak.git",
        "databeak"
      ]
    }
  }
}

For Other AI Clients

DataBeak works with Continue, Cline, Windsurf, and Zed. See the installation guide for specific configuration examples.

HTTP Mode (Advanced)

For HTTP-based AI clients or custom deployments:

# Run in HTTP mode
uv run databeak --transport http --host 0.0.0.0 --port 8000

# Access server at http://localhost:8000/mcp
# Health check at http://localhost:8000/health

Quick Test

Once configured, ask your AI assistant:

"Load a CSV file and show me basic statistics"
"Remove duplicate rows and export as Excel"
"Find outliers in the price column"

Documentation

📚 Complete Documentation

• Installation Guide - Setup for all AI clients
• Quick Start Tutorial - Learn in 10 minutes
• API Reference - All 40+ tools documented
• Architecture - Technical details

Environment Variables

Variable	Default	Description
DATABEAK_MAX_FILE_SIZE_MB	1024	Maximum file size
DATABEAK_CSV_HISTORY_DIR	"."	History storage location
DATABEAK_SESSION_TIMEOUT	3600	Session timeout (seconds)

Known Limitations

DataBeak is designed for interactive CSV processing with AI assistants. Be aware of these constraints:

• File Size: Maximum 1024MB per file (configurable via DATABEAK_MAX_FILE_SIZE_MB)
• Session Management: Maximum 100 concurrent sessions, 1-hour timeout (configurable)
• Memory: Large datasets may require significant memory; monitor with system_info tool
• CSV Dialects: Assumes standard CSV format; complex dialects may require pre-processing
• Concurrency: Single-threaded processing per session; parallel sessions supported
• Data Types: Automatic type inference; complex types may need explicit conversion
• URL Loading: HTTPS only; blocks private networks (127.0.0.1, 192.168.x.x, 10.x.x.x) for security

For production deployments with larger datasets, consider adjusting environment variables and monitoring resource usage.

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run quality checks: uv run -m pytest
5. Submit a pull request

Note: All changes must go through pull requests. Direct commits to main are blocked by pre-commit hooks.

Development

# Setup development environment
git clone https://github.com/jonpspri/databeak.git
cd databeak
uv sync

# Run the server locally
uv run databeak

# Run tests
uv run -m pytest tests/unit/          # Unit tests (primary)
uv run -m pytest                      # All tests

# Run quality checks
uv run ruff check
uv run mypy src/databeak/

Testing Structure

DataBeak implements comprehensive unit and integration testing:

• Unit Tests (tests/unit/) - 940+ fast, isolated module tests
• Integration Tests (tests/integration/) - 43 FastMCP Client-based protocol tests across 7 test files
• E2E Tests (tests/e2e/) - Planned: Complete workflow validation

Test Execution:

uv run pytest -n auto tests/unit/          # Run unit tests (940+ tests)
uv run pytest -n auto tests/integration/   # Run integration tests (43 tests)
uv run pytest -n auto --cov=src/databeak   # Run with coverage analysis

See Testing Guide for comprehensive testing details.

License

Apache 2.0 - see LICENSE file.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: jonpspri.github.io/databeak