shuck-file — Claude Code MCP server: documents to Markdown
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.
claude mcp add shuck-file -- uvx shuck-fileWhat shuck-file 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.
What it helps with
- 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 for the agent
- Convert
quarterly-report.pdfto Markdown and show me the section map - Give me the column headers and first 5 rows of
data.xlsx - Search
report.pdffor revenue mentions with--grep
How to install shuck-file
Platform CLI
claude mcp add shuck-file -- uvx shuck-fileuvx runs the command named after the package; if the README names another one, use uvx --from shuck-file <command>
Platform CLI
codex mcp add shuck-file -- uvx shuck-fileuvx runs the command named after the package; if the README names another one, use uvx --from shuck-file <command>
Config file
{
"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>
Config file
{
"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>
Platform CLI
gemini mcp add shuck-file uvx shuck-fileuvx runs the command named after the package; if the README names another one, use uvx --from shuck-file <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about shuck-file
How do I install shuck-file in Claude Code?
Run claude mcp add shuck-file -- uvx shuck-file. That registers the MCP server, and your agent gets the shuck and list_formats tools.
What does shuck-file do?
It converts documents to Markdown for AI agents. Small files are returned in full; large ones come back as a section map with token counts so the agent can read just the relevant parts.
Which file formats does shuck-file support?
Word (.docx), PDF, Excel (.xlsx), PowerPoint (.pptx) and CSV. Run shuck --formats or call the list_formats tool to see the list.
