TL;DR: a read-only MCP server that gives an AI assistant access to a student's data on the portal of FAM (Faculdade de Americana): grades, absences, assignments, schedule, exams, inbox, forums, finances and complementary hours. The portal has no API, so the server signs in as the student, reads the pages and hands back clean, typed JSON. It does not write anything back.
🎓 A read-only MCP server for my university’s student portal (FAM).
星數
4
工具
—
可用率
—
Why it exists
The portal does its job, but it was built for a browser and a patient person. There is no API, every screen is a full page rendered on the server that takes seconds to load, and the answer to a simple question is usually spread over several of them. What do I have to deliver this week? means the assignments, the forums, the exam calendar and the finance page.
With this server the assistant opens those pages for me, and I just ask. Some things I use it for:
"What is due this week?" reads the assignments, exams, forums and invoices in one go
"Can I still miss class in this course?" checks the absences against the allowed maximum
"What do I need on the last exam to pass?" reads the averages together with the portal's own grading rules
"How much of the degree is left?" adds up the transcript
How it works
Every tool is a small module. It asks the portal client for one or more pages, parses the HTML into a typed model, and returns it. The portal client keeps a single session for the whole run: it signs in when the server starts, notices when the portal sends it back to the login page, signs in again once and retries the request. Calls that arrive together share that one login.
What it can do
Student
Tools
What they do
get_student_profile
Who is signed in: name, RA, class, term and masked contact data
The courses of a term, with teachers and teaching-plan statusWhat happens on each weekdayScores per evaluation stage: N1, N2 and N3Averages, grading rules and the absences used so farHow many classes can still be missed, month by monthThe full grade history, semester by semesterHow much of the degree is done and what comes nextWhen the exams are
Assignments with deadline, status and whether they were deliveredOne assignment in full: instructions, materials and the deliverySaves an attached file so the assistant can read itEverything with a date in the next days, in one sorted list
Inbox messages, filtered by unread or senderOne message in full, with its attachmentsThe course forums and whether they are still openA forum's instructions and repliesThe institutional surveys and which ones were answered
Your FAM portal credentials: FAM_USERNAME is your CPF (digits only), and FAM_PASSWORD is your portal password.
Replace the example values with your credentials. Keep populated user configuration files private, and never commit real credentials to a repository.
Client-specific instructions
The examples below cover Claude Code, Claude Desktop, OpenAI Codex, OpenCode, Gemini CLI, Grok Build, DeepSeek Harness, Cursor, VS Code with GitHub Copilot, Zed, Cline, Roo Code, and Continue. Claude.ai and ChatGPT in a browser are covered too; they require a remote MCP server, while FAM MCP currently runs locally over stdio.
Run this in a terminal. The user scope makes FAM available in all your Claude Code projects:
claude mcp add --transport stdio --scope user \
--env "FAM_USERNAME=YOUR_CPF" \
--env "FAM_PASSWORD=YOUR_FAM_PASSWORD" \
fam -- uvx fam-mcp
Check the connection with claude mcp get fam or /mcp inside Claude Code. See the Claude Code MCP guide.
Open Settings → Developer → Edit Config and add this entry inside mcpServers:
In either extension's MCP settings, add a local stdio server with command uvx, argument fam-mcp, and environment variables FAM_USERNAME and FAM_PASSWORD. Both provide an MCP settings editor in the extension UI. See the Cline MCP guide and Roo Code MCP guide.
These web apps connect to remote MCP servers. FAM MCP currently runs locally over stdio and does not publish a remote endpoint, so you cannot paste uvx fam-mcp into their connector settings. Connecting a web app requires a separately hosted or securely tunneled remote MCP endpoint. See Claude remote connectors and ChatGPT MCP connectors.
Philosophy
Read-only, always.
It never submits, posts or answers anything on the portal. The only side effect comes from the portal itself: opening a message in the inbox marks it as read.
Questions, not screens.
The tools follow what a student actually asks, not how the portal's menu is organized. One question about what's coming up replaces four pages, and finding out how far along the degree is replaces adding up a transcript by hand.
Private by default.
Personal documents like the CPF and the RG come back hidden, other students' names and registration numbers are removed from forum replies, and the login stays in the environment instead of showing up in any answer.
Failures that explain themselves.
When something goes wrong, the assistant gets a clear answer: what happened, whether trying again makes sense and which tool it was. A portal that is down is told apart from a page that changed its layout, and the technical details stay in the log instead of reaching the assistant.
Gentle with a fragile site.
There is one shared session, renewed only when it expires. A call takes from a few seconds to about twenty, and doing several at once barely helps. The server doesn't hide that, and tells the assistant up front.
Shaped for the assistant.
Dates and numbers always come in the same format, and every id the assistant needs comes from a previous answer. The server also says where to start, so the assistant spends its calls on the answer instead of finding its way around.
What's inside
├── assets/ # the How it works diagram, as an editable Excalidraw file and its SVG
├── src/fam_mcp
│ ├── server.py # the MCP server: instructions, middleware and the login at startup
│ ├── portal.py # the session with the portal: login, re-login, retries, decoding
│ ├── middleware.py # turns every failure into the JSON error
│ ├── errors.py # the error hierarchy, one class per failure
│ ├── constants.py # the error codes and their messages
│ ├── utils.py # parsing helpers: dates, numbers, masking
│ ├── data/ # what the tools return, as dataclasses, one module per area
│ └── tools/ # one file per tool, registered automatically on import
└── pyproject.toml