Skip to main content
Glama

BanqueUNT MCP

CI Node License

An MCP server that connects the BanqueUNT medical question bank (1,400+ exam questions from the Universidad Nacional de Trujillo, Peru) to AI assistants such as Claude, Cursor and VS Code Copilot.

Students can search questions, take mock exams, get graded with detailed explanations and track their weak topics, all from a chat with their favorite assistant. The server is built so the assistant cannot see the answer key before grading, so the practice stays honest.

The full bank is private. This repository ships with a public sample of 30 questions from past exams, so everything below works out of the box.

Demo

Claude generates a 3-question Cardiology mock exam, grades the answers with explanations and suggests what to review

Claude Code with the bundled sample bank (in Spanish): generar_simulacro → the student answers → corregir_simulacro → mi_progreso.

Related MCP server: Moodle Study MCP

Features

Tools

Tool

What it does

estadisticas_banco

Counts questions by course, specialty, year and topic. Duplicates published in several exams count once.

buscar_preguntas

Full-text search (accent and case insensitive) with filters and cursor pagination. Never returns the answer.

generar_simulacro

Builds a random mock exam (1–100 questions), preferring questions the student has not seen yet. Stored with an expiry time.

corregir_simulacro

Grades a mock exam once: score, answer key and a normalized explanation for every wrong answer. Records results by topic.

mi_progreso

History, accuracy by specialty and topic, the 5 weakest topics and recently failed topics.

explicar_pregunta

Full explanation of a question the student has already answered and had graded.

Every tool declares an input and output schema with zod and returns structuredContent; read-only tools are annotated with readOnlyHint.

Resources and prompts

  • banqueunt://cursos, banqueunt://cursos/{curso}/temas (with argument completion) and banqueunt://pregunta/{id} (public version, no answer).

  • sesion_de_repaso: a tutor that asks one question at a time, waits for the answer, grades it and explains.

  • repasar_temas_debiles: reads your progress and builds a mock exam from your weak topics.

Use it remotely (BanqueUNT students)

The server is deployed on Cloudflare Workers. If you have a BanqueUNT account, you don't need to install anything: add this URL as a connector in your MCP client and sign in with your BanqueUNT email and password.

https://banqueunt-mcp.zumaetaadriel2.workers.dev/mcp
  • Claude.ai (web, desktop and mobile): Settings → Connectors → Add custom connector → paste the URL → Connect.

  • Claude Code: claude mcp add --transport http banqueunt https://banqueunt-mcp.zumaetaadriel2.workers.dev/mcp, then /mcp → banqueunt → Authenticate.

  • Cursor, VS Code and other clients that support remote MCP servers with OAuth: add it as a Streamable HTTP server with the same URL.

You only see the courses your BanqueUNT account has access to, and your progress is kept per account. Your password goes straight to BanqueUNT's sign-in and is never stored by the server.

Run it locally

Requires Node.js 22.13 or later (it uses the built-in node:sqlite).

git clone https://github.com/zumaetaadriel2/banqueunt-mcp.git
cd banqueunt-mcp
npm ci
npm run build

Then add the server to your client. Replace the path with the absolute path to dist/index.js on your machine.

Claude Code

claude mcp add --scope user banqueunt -- node /absolute/path/to/banqueunt-mcp/dist/index.js

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config) and restart the app:

{
  "mcpServers": {
    "banqueunt": {
      "command": "node",
      "args": ["C:\\path\\to\\banqueunt-mcp\\dist\\index.js"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "banqueunt": {
      "command": "node",
      "args": ["/absolute/path/to/banqueunt-mcp/dist/index.js"]
    }
  }
}

VS Code (GitHub Copilot agent mode)

Add to .vscode/mcp.json:

{
  "servers": {
    "banqueunt": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/banqueunt-mcp/dist/index.js"]
    }
  }
}

Then ask: "How many questions are there per specialty?" or "Give me a 10-question mock exam."

Configuration

All settings are environment variables, passed through the env field of your client config.

Variable

Default

Description

BANQUEUNT_DATA

(unset: bundled sample)

Path to a local bank folder containing index.json. File hashes are verified.

BANQUEUNT_CURSOS

med2_unt

Enabled courses, comma separated.

BANQUEUNT_DB

%LOCALAPPDATA%\banqueunt-mcp\progreso.db

SQLite file for mock exams and progress (~/.local/share/… on Linux and macOS).

BANQUEUNT_TOPE_DIARIO

(unset: no limit)

Maximum questions a user can receive per day (resets at midnight, Peru time).

Architecture

flowchart LR
  client["AI assistant<br/>(Claude, Cursor, VS Code)"] -- "MCP over stdio" --> server

  subgraph server["banqueunt-mcp"]
    tools["tools · resources · prompts"]
    dominio["domain<br/>search · mock exams · grading · progress"]
    publico["aPreguntaPublica()<br/>strips key, explanation and topic"]
    tools --> dominio
    dominio --> publico
  end

  dominio --> fuente["question source<br/>sample JSON or local bank folder"]
  dominio --> repo[("SQLite<br/>mock exams · results · call log")]
src/
  index.ts          stdio entry point
  worker.ts         Cloudflare Workers entry point: OAuth 2.1 + Streamable HTTP
  remoto/           remote mode: Supabase sign-in, token props, login rate limit, consent page, R2 bank
  server.ts         registers tools, resources and prompts
  datos/            zod schema, explanation normalizer, dedup signature, question sources
  dominio/          pure logic: search, mock exams, grading, progress, daily limit
  persistencia/     ProgresoRepo interface + SQLite (local) and Cloudflare D1 (remote) implementations
  tools/            one file per group of tools
tests/              Vitest: unit tests + end-to-end tests with a real MCP client in memory

Design decisions

  • No answer leaks before grading. Every pre-grading output goes through a single function, aPreguntaPublica(), which removes the key, the explanation and also the topic (a topic such as "Digoxin toxicity" gives the answer away). Integration tests serialize the response of every tool and fail if any of that appears.

  • Two explanation formats, one output. The bank mixes an old {correcta, descarte} format with a richer one (key idea, why each option is wrong, what to remember, reference). Both are validated with a zod union and normalized into a single Explicacion.

  • Deduplication. The same question often appears in several exams. A signature over the normalized stem and sorted options (ported from the original app) keeps counts and mock exams free of repeats.

  • Bank protection. Searches return at most 20 questions per call, an optional daily cap limits how many questions a user can receive, and every call is logged (npm run uso) to spot bulk extraction.

  • Async persistence interface. ProgresoRepo is async so the local SQLite implementation and the planned Cloudflare D1 one share the same contract.

Development

npm test            # Vitest (set BANQUEUNT_DATA to also validate the full bank)
npm run lint        # ESLint
npm run typecheck   # tsc --noEmit
npm run inspector   # open MCP Inspector against dist/index.js
npm run uso -- 7    # calls and questions served per user in the last 7 days

Roadmap

  • Test more clients (Cursor, ChatGPT, Gemini) against the remote server.

  • More courses (ENCIB, Residentado) and images.

  • npx banqueunt-mcp on npm.

License

Code under the MIT License. The bundled sample (data/muestra.json) contains questions from past exams for demonstration only; the full BanqueUNT bank is not part of this repository.

Available Tools

6 tools
buscar_preguntasBuscar preguntasA
Read-only

Busca preguntas del banco por texto y filtros. Devuelve enunciado y alternativas, nunca la respuesta ni la explicación. Para practicar con corrección usa generar_simulacro.

Inputs: anio, tema, curso, texto, +5 more. Returns: curso, total, preguntas, siguiente

corregir_simulacroCorregir simulacroA

Corrige un simulacro generado con generar_simulacro. Devuelve la nota, la clave de cada pregunta y la explicación de las falladas. Las preguntas sin respuesta cuentan como incorrectas. Cada simulacro se corrige una sola vez.

Inputs: respuestas (required), simulacro_id (required). Returns: curso, items, total, aciertos, +3 more

estadisticas_bancoEstadísticas del bancoA
Read-only

Cuenta las preguntas del banco por curso, especialidad y año (y por tema si se indica una especialidad). Las preguntas repetidas en varios exámenes se cuentan una sola vez. No devuelve preguntas ni respuestas.

Inputs: curso, especialidad. Returns: cursos, origen

explicar_preguntaExplicar preguntaA
Read-only

Devuelve la clave y la explicación completa de una pregunta que el alumno YA corrigió en un simulacro. No sirve para preguntas que todavía no respondió.

Inputs: pregunta_id (required). Returns: tema, pregunta, explicacion

generar_simulacroGenerar simulacroA

Arma un simulacro al azar con preguntas del banco, sin repetir y priorizando las que el alumno aún no vio. Devuelve un simulacro_id y las preguntas numeradas SIN respuesta. Muéstralas al alumno sin resolverlas y, cuando responda, llama a corregir_simulacro.

Inputs: anios, curso, temas, cantidad, +4 more. Returns: curso, total, nuevas, expira_en, +4 more

mi_progresoMi progresoA
Read-only

Resume los simulacros corregidos del alumno: porcentaje global, rendimiento por especialidad, temas débiles (2+ respuestas), temas fallados recientemente y últimos simulacros. Úsalo para recomendar qué repasar.

Inputs: curso. Returns: ultimos, aciertos, porcentaje, simulacros, +4 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a clearly distinct action in the study workflow: counting bank statistics, searching questions, generating a practice exam, summarizing progress, grading an exam, and explaining an already-graded question. The descriptions explicitly clarify boundaries, such as buscar_preguntas never returning answers and explicar_pregunta only working after correction.

    Naming Consistency4/5

    All names use consistent snake_case and are readable. However, four tools follow a verb_noun pattern (buscar_preguntas, generar_simulacro, corregir_simulacro, explicar_pregunta) while two use noun/possessive forms (estadisticas_banco, mi_progreso), a minor deviation from a single predictable convention.

    Tool Count5/5

    Six tools is well-scoped for a question-bank practice assistant. Each tool covers a necessary step in the student workflow without redundancy or filler.

    Completeness4/5

    The surface covers the core lifecycle: inspect bank stats, search questions, generate a simulacro, grade it, review progress, and explain missed questions. Minor gaps include no explicit tool to list available courses/specialties/themes for filter discovery, though estadisticas_banco partially surfaces that metadata.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers