CSV MCP Assistant

Ask questions about CSV or Excel data in plain English. This project combines a Streamlit chat interface, a LangGraph agent, and a custom FastAPI MCP server. The server uses Pandas to read the uploaded data; the agent decides which server tool to call and turns the result into a short answer.

In simple terms

1. Upload a CSV, .xlsx, or .xls file in the Streamlit sidebar.

2. The FastAPI server loads it into a Pandas DataFrame.

3. Ask a question such as How many employees left the company?.

4. The Groq model chooses a suitable MCP tool.

5. The server runs the Pandas operation and returns a small, structured result.

6. The model explains the result in the chat interface.

The model does not read the file directly. It requests data through the MCP server, which is the layer that performs the actual Pandas work.

Related MCP server: Claude Data Buddy

Architecture

User
  |
Streamlit UI
  |
LangGraph ReAct agent + Groq model
  |
MCP wrapper and JSON-RPC client
  |
FastAPI MCP server
  |
Pandas DataFrame (uploaded CSV / Excel file)

Example workflow: "Show employees whose age is greater than 30"

1. User types the question in Streamlit.
2. Streamlit sends the question to the LangGraph agent.
3. The Groq model decides that data is needed and selects query_dataframe.
4. The MCP wrapper translates that selection into an MCP tool call.
5. The custom MCP client sends a JSON-RPC POST request to FastAPI at /mcp.
6. FastAPI finds query_dataframe in its tool registry and runs it.
7. The server asks Groq for a safe Pandas expression, for example:
   df[df["Age"] > 30]
8. Pandas filters the active uploaded DataFrame on the server.
9. FastAPI returns a JSON-safe, bounded preview to the MCP client.
10. LangGraph gives that result to Groq, which writes the final answer.
11. Streamlit displays the answer to the user.

Role of each component

• Streamlit: The web chat interface. It accepts uploads and questions, then displays the assistant's answer.

• LangGraph: The agent workflow manager. It lets the model choose tools, call them, and continue reasoning from their result.

• Groq model: The language model that understands the user's question, decides what data is needed, and writes the natural-language reply.

• LangChain: The integration layer that represents tools and connects LangGraph to the Groq chat model.

• MCP (Model Context Protocol): The agreed format used for asking the data server to run a tool and return a result.

• MCP wrapper: A small adapter that exposes remote MCP tools as LangChain tools the agent can call.

• MCP client: Sends JSON-RPC requests from the agent side to the FastAPI server.

• FastAPI: The local HTTP server that receives MCP requests and file uploads.

• Tool registry and request handler: They match a requested tool name to Python code, run it, and format the MCP response.

• Pandas: Loads the CSV or Excel file into a DataFrame and performs filtering, counts, averages, and other data operations.

• Dataset manager: Keeps the currently uploaded DataFrame in memory so every server tool queries the same active dataset.

Features

• Upload CSV, XLSX, and XLS datasets.

• Start the local FastAPI server automatically from the Streamlit app.

• Query the currently uploaded dataset with natural-language questions.

• Use dedicated employee tools for the default employee dataset.

• Generate Pandas expressions for questions that do not match a dedicated tool.

• Log MCP tool calls, arguments, execution time, and returned row count.

MCP tools

• list_employees()

• get_employee(name)

• get_department(department)

• average_salary(department)

• highest_salary()

• count_department(department)

• query_dataframe(question) - for questions about an uploaded dataset.

Important changes and fixes

• The server now uses the dataset manager as the single source of the active DataFrame. Uploaded files are therefore used by query_dataframe instead of a stale hard-coded CSV path.

• Pandas, NumPy, date, and nested DataFrame values are converted to JSON-safe values before FastAPI returns them. This prevents HTTP 500 errors caused by response serialization.

• Tabular tool results are limited to the first 50 rows and include total_rows plus a truncated flag when more data exists. This keeps tool messages small enough for the model.

• Large list results are also limited to 50 items.

• The Groq agent's completion is capped at 1024 tokens, keeping answers focused and reserving context for tool results.

• Tool failures are returned as MCP error responses, and Streamlit displays a friendly error rather than a raw application crash.

• len(df) is permitted in the restricted Pandas-expression evaluator, so count queries work.

Why 50 rows worked but 4,000 rows caused a Groq 400 error

Yes. The reported error is a Groq/model context-size restriction, but it is not simply a limit on the number of rows in a CSV.

When a tool returns all 4,000 rows, LangGraph places that full response into the next message sent to Groq. The message must also include the system prompt, your question, tool definitions, earlier tool messages, and space for the model's answer. If their combined size is too large, Groq rejects the request with:

Please reduce the length of the messages or completion.

The size depends on the number of columns and the length of text in each cell, so 4,000 rows is not a universal threshold. A wide dataset or one containing long text can exceed the limit with far fewer rows.

The dataset itself can be larger than 4,000 rows because Pandas processes it locally. The restriction applies to how much of that dataset is sent back to the LLM in one tool response. The 50-row preview limit prevents the common overflow case.

For large datasets, ask focused questions such as:

How many rows are there?
What are the column names?
Show the average salary by department.
How many employees have LeaveOrNot equal to 1?
Show the first 10 employees from Bangalore.

Avoid asking the assistant to show every row of a large file. Use filters, counts, averages, groupings, or a small preview instead.

Running the project

streamlit run streamlit_app/app.py

Open the local Streamlit URL, upload a dataset, and ask a question. If the FastAPI server is restarted, upload the dataset again because the active dataset is held in server memory.

File guide

Project root

README.md Project documentation, setup notes, workflow explanation, and known limitations. It is the starting point for understanding and using the project.

requirements.txt Lists the main Python packages needed to run the application. Install these packages in the virtual environment before starting Streamlit.

.env Stores local secret configuration such as GROQ_API_KEY. Keep this file private and do not commit it to a public repository.

.env.example Provides a safe template showing the environment variables the project expects. Copy it to .env and add your own key values.

.gitignore Lists files Git should not track, such as virtual-environment files, secrets, and generated output. It helps prevent local or sensitive files from being committed accidentally.

server.log May be created in the project root when the application is run from that location. It is runtime logging output and can be safely regenerated.

streamlit_app/

streamlit_app/app.py Creates the Streamlit interface, including dataset upload and chat messages. It starts the local server when needed and sends user questions to the LangGraph agent.

streamlit_app/server_manager.py Checks whether FastAPI is already listening on port 8000. If it is not running, it starts Uvicorn for the FastAPI MCP server.

langgraph_agent/

langgraph_agent/agent.py Creates the Groq chat model and the LangGraph ReAct agent. It gives the agent its system prompt and the available tools.

langgraph_agent/config.py Loads environment variables from .env. It provides the Groq API key to the agent configuration.

langgraph_agent/prompts.py Contains the system instructions for the data assistant. It tells the model when to use dedicated tools and when to use query_dataframe.

langgraph_agent/tools.py Defines the LangChain tools the agent is allowed to select. Each tool forwards its work to the MCP wrapper rather than reading data directly.

langgraph_agent/mcp_wrapper.py Initializes the MCP client and translates agent tool calls into remote MCP calls. It unwraps successful responses and returns readable MCP errors to the agent.

langgraph_agent/test_agent.py Provides a terminal-based loop for trying the LangGraph agent without Streamlit. Use it for quick manual testing of questions and answers.

langgraph_agent/test_wrapper.py Calls selected wrapper functions directly for a lightweight connectivity test. It helps verify agent-side communication with the MCP server.

mcp_client/

mcp_client/client.py Implements the custom JSON-RPC MCP client using HTTP requests. It supports initialization, tool listing, and tool execution requests.

mcp_client/test_client.py Tests the MCP protocol directly from the command line. It is useful for checking the server before involving LangGraph or Streamlit.

fastapi_mcp_server/

fastapi_mcp_server/main.py Defines FastAPI endpoints for /upload and /mcp. It receives files and MCP requests, then returns safe protocol responses.

fastapi_mcp_server/request_handler.py Handles MCP methods such as initialize, tools/list, and tools/call. It locates a requested tool in the registry and records its execution.

fastapi_mcp_server/registry.py Lists every server tool along with its description and input schema. This is the server-side catalogue used to validate tool calls.

fastapi_mcp_server/tools.py Contains the Pandas functions that perform employee and generic dataset queries. It limits large results and converts them into JSON-safe data before returning them.

fastapi_mcp_server/dataset_manager.py Loads the default or uploaded dataset and stores it as the active in-memory DataFrame. It also returns metadata such as filename, row count, and column names.

fastapi_mcp_server/llm_query.py Asks the Groq-compatible model to turn a natural-language question into a Pandas expression. The expression is later evaluated against the active DataFrame by tools.py.

fastapi_mcp_server/data_loader.py Contains the original fixed-path CSV loader for the default employee file. The active application now uses dataset_manager.py; this file is retained as legacy code.

fastapi_mcp_server/constants.py Defines MCP protocol, server-name, and server-version constants. Keeping these values in one place makes the protocol response easier to maintain.

fastapi_mcp_server/jsonrpc.py Builds standard JSON-RPC success and error response dictionaries. It keeps protocol formatting separate from the request-handling logic.

fastapi_mcp_server/logger.py Configures server logging and measures tool execution time. It writes tool name, arguments, duration, and returned row count to server.log.

fastapi_mcp_server/models.py Defines a Pydantic request model for tool-related data. It is available for typed FastAPI validation as the server grows.

fastapi_mcp_server/requirements.txt Contains a detailed environment package list for the server setup. The root requirements.txt is the simpler dependency list for normal project use.

fastapi_mcp_server/server.log Created while the server runs and records MCP tool activity. It is runtime output, not application source code.

data/

data/employees.csv The small default employee dataset used by the original dedicated employee tools. It is loaded automatically when the FastAPI server starts.

data/Employeekaggale.csv An example larger employee dataset used for testing uploads and large-result behavior. It is data only; the application does not automatically select it unless uploaded.

data/newemployee.csv An additional example employee dataset for upload testing. It can be used to verify questions against a different file structure or row count.

fastapi_mcp_server/uploads/

fastapi_mcp_server/uploads/employees.csv A saved copy created when the default employee CSV is uploaded through the UI. It is a runtime upload file, not the default source file.

fastapi_mcp_server/uploads/Employeekaggale.csv A saved copy of the larger employee dataset after it was uploaded. It is used only when the server has that upload loaded as its active in-memory dataset.

fastapi_mcp_server/uploads/newemployee.csv A saved copy of the newemployee.csv upload. Like other upload files, it must be uploaded again after a server restart.

Technologies

• Python

• Streamlit

• FastAPI and Uvicorn

• Model Context Protocol (MCP) over JSON-RPC

• LangGraph and LangChain

• Groq (openai/gpt-oss-120b)

• Pandas