# shuck-file

Turns Word, PDF, Excel, PowerPoint and CSV files into clean Markdown. Large files come back as a section map so the agent reads only what it needs.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 6
- Author: Shan-Zhu
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Shan-Zhu/shuck-file
- Updated: 2026-03-20
- HTML: https://affpapa.org/en/nevibecode/mcp/shuck-file

## What it does

shuck-file runs as an MCP server and exposes two tools to your agent: `shuck` for conversion and `list_formats` for the supported extensions. Each format has its own extractor — `python-docx` handles `.docx`, `pdfplumber` reads `.pdf`, `openpyxl` covers `.xlsx`, `python-pptx` takes `.pptx`, and `.csv` goes through the standard library. Word keeps headings, bold and italic runs, lists and tables. PDF keeps text and page breaks. Excel sheets all become Markdown tables.

Routing is automatic. A small file prints straight to stdout. A large one returns a document map listing sections, token estimates and suggested follow-up commands. From there you can pull specific sections with `--sections s1,s3`, search inside the file with `--grep`, grab tables only, or cap the output with `--budget 4000`. The `probe` subcommand forces map mode, `pull` is an alias for `--all`.

\`pip install shuck-file` brings both the `shuck` CLI and the server. The connection commands call `uvx shuck-file`, so `uvx` has to be on your machine — without it the server never starts and the agent sees no tools at all.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add shuck-file -- uvx shuck-file
```
uvx runs the command named after the package; if the README names another one, use uvx --from shuck-file <command>

### Codex

**Platform CLI**
```bash
codex mcp add shuck-file -- uvx shuck-file
```
uvx runs the command named after the package; if the README names another one, use uvx --from shuck-file <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "shuck-file": {
            "command": "uvx",
            "args": [
                "shuck-file"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from shuck-file <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "shuck-file": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "shuck-file"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from shuck-file <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add shuck-file uvx shuck-file
```
uvx runs the command named after the package; if the README names another one, use uvx --from shuck-file <command>

## When to use it
- read a long PDF without flooding the context window
- pull Excel sheets out as Markdown tables
- locate a keyword inside a report
- summarise a deck including speaker notes
- fit a document into a fixed token budget

## Example prompts
- Convert `quarterly-report.pdf` to Markdown and show me the section map
- Give me the column headers and first 5 rows of `data.xlsx`
- Search `report.pdf` for revenue mentions with `--grep`

## Similar
- [Excel MCP Server](https://affpapa.org/en/nevibecode/mcp/excel-mcp-server.md) — MCP server · ★ 4259
- [kordoc](https://affpapa.org/en/nevibecode/mcp/kordoc.md) — MCP server · ★ 2726
- [Power BI Authoring MCP Server (Local)](https://affpapa.org/en/nevibecode/mcp/power-bi-authoring-mcp-server-local.md) — MCP server · ★ 1247
- [Microsoft 365 MCP Server](https://affpapa.org/en/nevibecode/mcp/microsoft-365-mcp-server.md) — MCP server · ★ 1074
- [anymd](https://affpapa.org/en/nevibecode/mcp/anymd.md) — MCP server · ★ 1051
- [Docling MCP](https://affpapa.org/en/nevibecode/mcp/docling-mcp.md) — MCP server · ★ 777

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md