veera-0/python-csv-mcp

Titanic CSV MCP Project

This project provides a Model Context Protocol (MCP) server for exploring and analyzing the Titanic dataset (titanic.csv) using a set of simple, composable tools. The server is implemented in Python and exposes a variety of data exploration and analysis functions, making it easy to interact with the dataset programmatically or via LLMs.

Project Structure

main.py           # Main MCP server with tool definitions
prepare_csv.py    # (Optional) Script for preparing or cleaning the CSV
`titanic.csv`     # Titanic dataset (input data)

Response Screenshot

Features

• Load and explore the Titanic dataset using pandas
• Expose useful data analysis tools as MCP endpoints
• Tools return structured (JSON or CSV) responses for easy parsing
• Easily extensible: add your own tools for custom analysis

Available Tools

Schema & Nulls

• tool_schema: Returns column names and data types as JSON.
• tool_nulls: Returns columns with the number of missing values as JSON (only columns with >0 missing values).

Data Exploration

• tool_head(n): Returns the first n rows of the dataframe as CSV (default 5).
• tool_describe([columns]): Returns describe() statistics for all or selected columns as CSV.
• tool_value_counts(col): Returns value counts for a given column as JSON.
• tool_unique_values(col): Returns unique values for a given column as a JSON list.
• tool_fillna_count(col, value): Returns the number of missing values that would be filled for a given column and value as JSON.

Getting Started

Prerequisites

• Python 3.7+
• pip (Python package manager)

Installation

1. Clone the repository or copy the project files to your workspace.
2. Install required dependencies:

   pip install pandas
   # If using MCP server framework:
   pip install fastmcp
   

3. Ensure titanic.csv is present in the project directory.

Running the MCP Server

Run the main server:

python main.py

The server will start and expose the defined tools via MCP (Model Context Protocol). You can interact with it using compatible clients or LLMs.

Example Usage

• Get the schema:
  • tool_schema("")
• Get columns with missing values:
  • tool_nulls("")
• Get the first 10 rows:
  • tool_head("10")
• Get value counts for the 'sex' column:
  • tool_value_counts("sex")
• Get unique values for the 'embarked' column:
  • tool_unique_values("embarked")
• Get describe statistics for 'age' and 'fare':
  • tool_describe("age, fare")
• Get how many missing values would be filled in 'age' with value 30:
  • tool_fillna_count("age,30")

3. How to Add MCP Config in mcp.json

1. Open (or create) .vscode/mcp.json or your user mcp.json file.
2. Add your server configuration as below:

{
  "servers": {
    "my-mcp-server-662ce895": {
      "type": "stdio",
      "command": "python",
      "cwd": "e:/git/python-csv-mcp",
      "args": [
        "main.py"
      ]
    }
  },
  "inputs": []
}

• type: Use stdio for a standard Python MCP server.
• command: The command to run (e.g., python).
• cwd: The working directory (absolute path to your project).
• args: Arguments to pass to the command (your main script).

Save the file and restart VS Code or reload the MCP extension to apply changes.

Extending the Project

To add more tools, simply define new functions in main.py and decorate them with @mcp.tool(). Each tool should return a string (preferably JSON or CSV) for easy parsing.