StudyTools MCP

A Model Context Protocol (MCP) server that exposes four study tools — PDF summarization, flashcard generation, math/code problem solving, and trust-filtered web search — to any MCP-compatible client (Claude Desktop, MCP Inspector, custom agents, etc.).

See Student_MCP_Server_PRD.md and Student_MCP_Server_TechStack.md for the full spec and design rationale.

Tools

Prerequisites

• Python 3.10+

• A free Groq API key (LLM calls)

• A free Tavily API key (web search)

Local setup

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

pip install -r requirements.txt
cp .env.example .env            # then fill in GROQ_API_KEY and TAVILY_API_KEY

Running locally

MCP Inspector (browser UI to call tools directly, no client wiring needed):

mcp dev server.py

Opens a browser at localhost:6274 listing all four tools — fill in inputs and run them.

Claude Desktop: add an entry to your claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json; some installs — e.g. Microsoft Store builds — sandbox this under %LOCALAPPDATA%\Packages\<PackageName>\LocalCache\Roaming\Claude\):

{
  "mcpServers": {
    "studytools": {
      "command": "C:\\path\\to\\project\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\project\\server.py"]
    }
  }
}

Fully quit and relaunch Claude Desktop afterward, then check the tools/connectors icon in a new chat for studytools.

By default the server runs over stdio (MCP_TRANSPORT unset). No host/port needed for local client use.

Deploying

The server supports streamable-http in addition to stdio, needed for any remotely hosted deployment (a hosted process can't run stdio the way a local desktop client does).

AWS EC2 (free tier) — primary target

Uses a t2.micro/t3.micro instance (750 hrs/month free for 12 months) running the server as a systemd service so it survives reboots and restarts on crash.

1. Launch an instance: Ubuntu 22.04/24.04, t2.micro or t3.micro (free-tier eligible), with a key pair you can SSH in with.

2. Security group: allow inbound

   • port 22 (SSH) from your IP only, not 0.0.0.0/0

   • port 8000 (the MCP endpoint) from 0.0.0.0/0 if you want it publicly reachable, or restrict it to known client IPs — note there's no auth in front of the server (matches the PRD's v1 scope, which excludes multi-user auth), so anything with network access can call your tools and consume your Groq/Tavily quota.

3. SSH in, clone the repo, and run the setup script:

   git clone <your-repo-url> studytools-mcp
   cd studytools-mcp
   bash deploy/setup_ec2.sh

   This installs Python deps into a venv, creates .env from .env.example if missing, and registers/starts deploy/studytools-mcp.service via systemd.

4. Add your real API keys: nano .env, fill in GROQ_API_KEY and TAVILY_API_KEY, then sudo systemctl restart studytools-mcp.

5. Verify: curl http://<ec2-public-ip>:8000/mcp (a 400/406 response is expected from a bare curl request — it means the server is up; a real MCP client will complete the full handshake). Logs: sudo journalctl -u studytools-mcp -f.

This serves plain HTTP, not HTTPS — fine for a free-tier demo, but note it if you ever point a client that requires TLS at it (adding an Nginx reverse proxy + Let's Encrypt would be the next step, out of scope for v1).

Render — alternative

render.yaml is included as a documented fallback if you'd rather not manage a server yourself:

1. Push this repo to GitHub/GitLab/Bitbucket.

2. In Render, choose New > Blueprint and point it at the repo — it reads render.yaml and provisions the service automatically.

3. Add GROQ_API_KEY and TAVILY_API_KEY under the service's Environment tab (marked sync: false in the blueprint, so Render won't set them for you).

4. The MCP endpoint is reachable at https://<your-service>.onrender.com/mcp.

If Render's health check fails against / (the MCP route only exists at /mcp), set the service's Health Check Path to /mcp in the dashboard.

Project structure

app.py                  # FastMCP instance, host/port/env config
llm.py                  # Groq client wrapper (chat_completion, JSON mode)
server.py               # Entrypoint — registers tools, runs stdio or streamable-http
tools/
  pdf_tools.py           # summarize_pdf
  flashcard_tools.py     # generate_flashcards
  solve_tools.py         # solve_and_explain
  search_tools.py        # web_search
deploy/
  studytools-mcp.service # systemd unit for AWS EC2
  setup_ec2.sh            # EC2 provisioning script
requirements.txt
render.yaml              # Render Blueprint (alternative deploy path)
.env.example