`peekmcp`

Zero-dependency MCP server and CLI that lets AI agents inspect local CSV/JSON/JSONL files without dumping entire files into context.

License Language Status PyPI Python MCP License

🎯 Why?

Trending repos show heavy investment in MCP, agent context pipelines, and token-efficient tooling, but most file MCP servers expose raw bytes or require databases. Developers frequently have quick CSV/JSON/JSONL artifacts that agents need to inspect without loading entire files into context. PeekMCP fills that gap with a zero-dependency stdio MCP server and CLI that provides schema, samples, and paginated filtered queries.

Target audience: AI agent developers, data engineers, and local LLM users who need safe, token-efficient access to flat files during coding, analysis, and automation.

✨ Features

✨ Zero-dependency MCP stdio server with list_files, inspect_file, and query_table tools
✨ CLI for listing, inspecting, and querying CSV/TSV/JSON/JSONL files
✨ Token-saving pagination, column selection, substring filtering, and truncated cells

🚀 Quick Start

# Install
pip install peekmcp

# Run
peekmcp --help

📦 Installation

From Source

git clone https://github.com/YOUR_USERNAME/peekmcp.git
cd peekmcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest -v

🎬 Demo

The GIF above was recorded using Charm VHS:

vhs < demo.tape

📖 Usage

# Show help
peekmcp --help

# Common usage examples
peekmcp --example

🏗️ Architecture

graph LR
    A[Input] --> B[Core Engine]
    B --> C[Output]
    B --> D[Plugins]
    D --> E[Extensions]

🤝 Contributing

Contributions are welcome! Please:

Fork the repo
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

If this project helped you, please ⭐ star it!

Made with ❤️ and AI