Review Analysis MCP Server

A local, privacy-friendly pipeline for analyzing customer reviews. An MCP client (VS Code, Claude Desktop, …) drives a FastMCP server whose tools call a local Ollama model (Llama 3.1) to classify sentiment, surface recurring issues, and generate reports. A Streamlit dashboard visualizes the results.

MCP client  ──MCP──▶  FastMCP server ──▶ Ollama (Llama 3.1)
                          │
                          ▼
                   data/store.json  ◀──reads──  Streamlit dashboard

Tools

Tool	Description
upload_reviews(csv_text | reviews, replace)	Ingest reviews from CSV text or a list of dicts.
analyze_sentiment()	Classify each review positive / neutral / negative.
get_top_issues(limit)	Cluster complaints into the top recurring issues.
generate_report()	Render a markdown report from the analysis.

Setup

# 1. Python deps
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2. Local LLM
#    Install Ollama from https://ollama.com, then:
ollama pull llama3.1
ollama serve        # if not already running as a service

Run

MCP server (stdio transport):

python server.py

Register it with your client. Example Claude Desktop / VS Code MCP config:

{
  "mcpServers": {
    "review-analyzer": {
      "command": "/Users/chandangowda/Desktop/mcp/.venv/bin/python",
      "args": ["/Users/chandangowda/Desktop/mcp/server.py"]
    }
  }
}

Point command at the Python inside your virtualenv (as above) so the server starts with mcp, ollama, etc. already installed.

Run with the MCP Inspector

The MCP Inspector is a browser UI for calling the server's tools by hand — the fastest way to try the pipeline without wiring up a full client.

# From the project root, with the virtualenv active:
source .venv/bin/activate
mcp dev server.py

This launches the Inspector and prints a local URL (default http://localhost:6274). Open it in your browser, then:

1. Connect — the transport is already set to stdio with the command pre-filled from server.py. Click Connect.
2. Open the Tools tab and click List Tools to see the four tools: upload_reviews, analyze_sentiment, get_top_issues, generate_report.
3. Run them in order:
   • upload_reviews — paste the contents of data/sample_reviews.csv into the csv_text field (leave replace as true), then Run Tool. You should see {"uploaded": 15, "total_reviews": 15}.
   • analyze_sentiment — no arguments; Run Tool. Returns the sentiment distribution. (Requires ollama serve running.)
   • get_top_issues — optionally set limit (default 5); Run Tool.
   • generate_report — no arguments; Run Tool. Returns the final markdown report.

Prerequisites: ollama serve must be running and llama3.1 pulled (see Setup), otherwise the analysis tools return an LLMError. If the mcp command isn't found, install the CLI extra with pip install "mcp[cli]".

Dashboard:

streamlit run dashboard/app.py

Try it end to end

1. Start ollama serve and the dashboard.
2. In the dashboard sidebar, upload data/sample_reviews.csv → Ingest CSV.
3. Click Run sentiment analysis, Find top issues, Generate report.
4. Or drive the same flow from your MCP client by calling the tools.

Configuration

Env var	Default	Purpose
OLLAMA_MODEL	llama3.1	Which Ollama model to use.
OLLAMA_HOST	(library default)	Ollama server URL, e.g. http://localhost:11434.
REVIEW_STORE_PATH	data/store.json	Where shared state is persisted.

Notes

• The server and dashboard are separate processes; they communicate only through data/store.json (atomic writes, so readers never see partial data).
• Uploading new reviews clears any prior analysis for that dataset.
• Swapping to OpenAI/GPT-4o later means implementing the same chat_json contract in src/llm.py — nothing else changes.