file-analysis

The File Analysis MCP Server provides tools for reading and writing text files, extracting text from PDFs, sampling and analyzing CSV data, and generating visualizations. It is designed to be queried by MCP clients like Claude Desktop, enabling interactive file operations, data analysis, and quick plots directly from your filesystem within the permitted directories. Use cases include reading file contents, listing and filtering files, extracting PDF text, performing CSV statistics and sampling, and creating visuals such as bar, line, scatter, histogram, and box plots from your data. The server enforces path validation to ensure you can only access files within the configured safe directories (defaulting to ~/Documents and ~/Downloads unless you customize MCP_FILE_ROOTS).

To use the capabilities, install the server into Claude Desktop or your MCP client, then invoke prompts such as reading a file, extracting text from a PDF, analyzing a CSV’s statistics, or generating a chart from a CSV column. For example, you can ask the agent to read ~/Documents/notes.txt, extract text from a PDF like ~/Documents/report.pdf, analyze a CSV at ~/Downloads/sales_data.csv, or create a bar chart of a specific column. The included prompts help structure workflows for data analysis, data cleaning, summaries, and exploratory data analysis.

Prerequisites:

• Python 3.10 or higher
• Claude Desktop or another MCP client

Step-by-step installation:

1. Create and activate a Python environment (optional but recommended):

python -m venv venv
source venv/bin/activate  # on macOS/Linux
venv\Scripts\activate     # on Windows

2. Install required packages:

pip install "mcp[cli]" pandas numpy matplotlib PyPDF2

3. (Optional) Configure safe directories (MCP_FILE_ROOTS) to restrict access:

# Default directories are ~/Documents and ~/Downloads
# To customize, set this environment variable:
export MCP_FILE_ROOTS="~/Documents:~/Downloads"

4. Install the server in Claude Desktop:

mcp install file_analysis_server.py

5. (Development/testing) Run in development mode to test interactively:

mcp dev file_analysis_server.py

Tips and considerations:

• The server relies on MCP_FILE_ROOTS to restrict file system access. Set this to include only the folders you trust.
• When analyzing CSVs, you can request statistics, sampling, and visualizations directly via prompts. If a column contains non-numeric data, specify the target numeric columns for plots.
• If PDF text extraction seems limited, ensure PyPDF2 is installed and the PDF is not secured against text extraction.
• For large CSV files, consider requesting sampling (e.g., first N rows) to get quick insights before full analysis.
• If you encounter path-related errors, verify that the target path falls within the configured MCP_FILE_ROOTS and that the path is correctly expanded (e.g., ~ expands to your home directory).