Databeak

🚀 DataBeak

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

Badges

🚀 Quick Start

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

For Claude Desktop

Add the following to your MCP Settings file:

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

For Other AI Clients

DataBeak is compatible with Continue, Cline, Windsurf, and Zed. Refer to 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, you can ask your AI assistant the following commands:

"Load this CSV data: name,price\nWidget,10.99\nGadget,25.50"
"Load CSV from URL: https://example.com/data.csv"
"Remove duplicate rows and show me the statistics"
"Find outliers in the price column"

✨ Features

• 🔄 Complete Data Operations: Load, transform, and analyze CSV data from URLs and string content.
• 📊 Advanced Analytics: Perform statistics, correlations, outlier detection, and data profiling.
• ✅ Data Validation: Conduct schema validation, quality scoring, and anomaly detection.
• 🎯 Stateless Design: Clean MCP architecture with external context management.
• ⚡ High Performance: Utilize async I/O, streaming downloads, and chunked processing.
• 🔒 Session Management: Support multiple users with isolated sessions.
• 🛡️ Web-Safe: No file system access, designed for secure web hosting.
• 🌟 Code Quality: Zero ruff violations, 100% mypy compliance, perfect MCP documentation standards, and comprehensive test coverage.

📚 Documentation

• 📚 Complete Documentation
  • Installation Guide: Setup instructions for all AI clients.
  • Quick Start Tutorial: Learn to use DataBeak in 10 minutes.
  • API Reference: Documentation for all 40+ tools.
  • Architecture: Technical details of DataBeak.

🔧 Environment Variables

Configure DataBeak's behavior using environment variables (all prefixed with DATABEAK_):

Refer to settings.py for complete configuration options.

⚠️ Known Limitations

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

• Data Loading: Supports only URLs and string content (no local file system access for web hosting security).
• Download Size: Maximum 100MB per URL download (configurable via DATABEAK_MAX_DOWNLOAD_SIZE_MB).
• DataFrame Size: Maximum 1GB memory and 1M rows per DataFrame (configurable).
• Session Management: Maximum 100 concurrent sessions with a 1 - hour timeout (configurable).
• Memory: Large datasets may require significant memory; monitor using the health_check tool.
• CSV Dialects: Assumes standard CSV format; complex dialects may need pre - processing.
• Concurrency: Async I/O for concurrent URL downloads; parallel sessions are supported.
• Data Types: Automatic type inference; complex types may need explicit conversion.
• URL Loading: Supports 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, adjust environment variables and monitor resource usage using the health_check and get_server_info tools.

👥 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Make your changes and include 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 has comprehensive unit and integration testing:

• Unit Tests (tests/unit/): Over 940 fast, isolated module tests.
• Integration Tests (tests/integration/): 43 FastMCP Client - based protocol tests across 7 test files.
• E2E Tests (tests/e2e/): Planned for 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

Refer to the Testing Guide for comprehensive testing details.

📄 License

DataBeak is licensed under the Apache 2.0 license. See the LICENSE file for details.

🛠️ Support

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