Skip to content
Back to search

QueraMCP

An MCP server that connects Quera to AI agents and LLMs, enabling intelligent course exploration, problem solving, submission management, and evaluation workflows.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/amirmj-z--queramcp/badge.svg)](/listings/amirmj-z--queramcp)

HTML

<a href="/listings/amirmj-z--queramcp"><img src="/api/listings/amirmj-z--queramcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Python 3.10 or newer. - A working Quera account. - Git. - A compatible MCP client. - Any additional browser dependencies required by your Quera Client authentication implementation.

1. Clone the repository

git clone https://github.com/AmirMJ-Z/QUeraMCP.git
cd QueraMCP

2. Create a virtual environment

QueraMCP uses a standard Python virtual environment.

python3 -m venv .venv

Activate it:

**Linux / macOS**

source .venv/bin/activate

**Windows (PowerShell)**

.venv\Scripts\Activate.ps1

3. Install dependencies

python -m pip install --upgrade pip
pip install -r requirements.txt

4. Configure environment variables

Create a `.env` file in the project root:

touch .env

Add your Quera credentials and configuration:

QUERA_USERNAME="your_quera_username"
QUERA_PASSWORD="your_quera_password"

QUERA_LOGIN_URL="https://quera.org/accounts/api/login/verify"
QUERA_MANUAL_LOGIN_URL="https://quera.org/accounts/login"
QUERA_COURSES_URL="https://quera.org/course"
QUERA_ASSIGNMENT_URL="https://quera.org/course/{}"
QUERA_PROBLEMS_URL="https://quera.org/course/assignments/{}/problems"
QUERA_PROBLEM_URL="https://quera.org/course/assignments/{}/problems/{}"
QUERA_DASHBOARD_URL="https://quera.org/dashboard"
QUERA_SUBMISSIONS_URL="https://quera.org/course/assignments/{}/submissions/all?page={}"
QUERA_SUBMISSION_ACTION_URL="https://quera.org/assignment/submission_action"

Replace the credentials with your own.

**Never commit your `.env` file or share your Quera credentials.**

5. Run the server

python server.py

QueraMCP uses STDIO transport. When launched directly, it waits for an MCP client to communicate with it. An apparently idle terminal is normal.

Stop the server with `Ctrl+C`.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 734 lines
  1. <div align="center">
  2. <img src="images/queramcp-logo.png" alt="QueraMCP" width="650">
  3. ### Quera, accessible to your AI agents.
  4. **An MCP server that connects Quera to AI assistants, coding agents, and LLM-powered workflows.**
  5. [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
  6. [![MCP](https://img.shields.io/badge/Protocol-MCP-8A2BE2?style=for-the-badge)](https://modelcontextprotocol.io/)
  7. [![FastMCP](https://img.shields.io/badge/Powered%20by-FastMCP-00A67E?style=for-the-badge)](https://github.com/PrefectHQ/fastmcp)
  8. [![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey?style=for-the-badge)](#)
  9. [![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
  10. [Features](#-features) · [Installation](#-installation) · [Available Tools](#-available-tools) · [AI Client Setup](#-connecting-to-ai-agents) · [Security](#-security)
  11. </div>
  12. ---
  13. ## What is QueraMCP?
  14. **QueraMCP** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives compatible AI assistants access to Quera through a collection of structured tools.
  15. Instead of manually navigating Quera, retrieving problem statements, checking submissions, and tracking evaluation results, you can let your AI agent interact with these capabilities directly.
  16. Connect QueraMCP to your preferred AI client and turn your assistant into a Quera-aware development companion.
  17. ### Why MCP?
  18. MCP provides a standardized interface between AI applications and external tools. This means QueraMCP is not tied to a particular LLM, model provider, or AI application.
  19. You can use it with compatible clients such as:
  20. - OpenCode
  21. - Claude Desktop
  22. - Claude Code
  23. - Cursor
  24. - Visual Studio Code (GitHub Copilot)
  25. - Windsurf
  26. - Cline
  27. - Gemini CLI
  28. - OpenAI Codex
  29. - Other MCP-compatible applications
  30. ---
  31. ## Features
  32. - **Course discovery** — Retrieve your Quera courses.
  33. - **Assignment exploration** — Browse assignments and retrieve their details.
  34. - **Problem retrieval** — Access problem statements and metadata.
  35. - **Submission history** — Inspect previous submissions and their scores.
  36. - **Evaluation inspection** — Retrieve submission results.
  37. - **Code submission** — Submit source code through Quera.
  38. - **Submission management** — Mark submissions as final.
  39. - **Current time** — Retrieve the current time exposed by the Quera client.
  40. - **AI-agent integration** — Use Quera functionality directly from compatible MCP clients.
  41. - **Local execution** — Run the server on your own machine using STDIO transport.
  42. ### Designed for AI-assisted problem solving
  43. QueraMCP can be combined with project-level agent instructions to support a structured problem-solving workflow:
  44. 1. Retrieve a problem from Quera.
  45. 2. Understand its requirements and constraints.
  46. 3. Develop an implementation.
  47. 4. Review the implementation before submission.
  48. 5. Submit the solution after explicit authorization.
  49. 6. Inspect the evaluation result.
  50. 7. Analyze available feedback and identify potential issues.
  51. 8. Revise the implementation and repeat the process when authorized.
  52. The goal is to make the entire workflow accessible to an AI agent while keeping important actions under the user's control.
  53. ---
  54. ### Technology stack
  55. | Component | Technology |
  56. |---|---|
  57. | Language | Python |
  58. | MCP implementation | FastMCP |
  59. | Communication | MCP over STDIO |
  60. | Authentication | Quera Client |
  61. | HTTP communication | Requests |
  62. | Configuration | Environment variables / `.env` |
  63. ---
  64. ## 📦 Installation
  65. ### Prerequisites
  66. - Python 3.10 or newer.
  67. - A working Quera account.
  68. - Git.
  69. - A compatible MCP client.
  70. - Any additional browser dependencies required by your Quera Client authentication implementation.
  71. ### 1. Clone the repository
  72. ```bash
  73. git clone https://github.com/AmirMJ-Z/QUeraMCP.git
  74. cd QueraMCP
  75. ```
  76. ### 2. Create a virtual environment
  77. QueraMCP uses a standard Python virtual environment.
  78. ```bash
  79. python3 -m venv .venv
  80. ```
  81. Activate it:
  82. **Linux / macOS**
  83. ```bash
  84. source .venv/bin/activate
  85. ```
  86. **Windows (PowerShell)**
  87. ```powershell
  88. .venv\Scripts\Activate.ps1
  89. ```
  90. ### 3. Install dependencies
  91. ```bash
  92. python -m pip install --upgrade pip
  93. pip install -r requirements.txt
  94. ```
  95. ### 4. Configure environment variables
  96. Create a `.env` file in the project root:
  97. ```bash
  98. touch .env
  99. ```
  100. Add your Quera credentials and configuration:
  101. ```env
  102. QUERA_USERNAME="your_quera_username"
  103. QUERA_PASSWORD="your_quera_password"
  104. QUERA_LOGIN_URL="https://quera.org/accounts/api/login/verify"
  105. QUERA_MANUAL_LOGIN_URL="https://quera.org/accounts/login"
  106. QUERA_COURSES_URL="https://quera.org/course"
  107. QUERA_ASSIGNMENT_URL="https://quera.org/course/{}"
  108. QUERA_PROBLEMS_URL="https://quera.org/course/assignments/{}/problems"
  109. QUERA_PROBLEM_URL="https://quera.org/course/assignments/{}/problems/{}"
  110. QUERA_DASHBOARD_URL="https://quera.org/dashboard"
  111. QUERA_SUBMISSIONS_URL="https://quera.org/course/assignments/{}/submissions/all?page={}"
  112. QUERA_SUBMISSION_ACTION_URL="https://quera.org/assignment/submission_action"
  113. ```
  114. Replace the credentials with your own.
  115. **Never commit your `.env` file or share your Quera credentials.**
  116. ### 5. Run the server
  117. ```bash
  118. python server.py
  119. ```
  120. QueraMCP uses STDIO transport. When launched directly, it waits for an MCP client to communicate with it. An apparently idle terminal is normal.
  121. Stop the server with `Ctrl+C`.
  122. ---
  123. ## Available Tools
  124. QueraMCP exposes the following MCP tools.
  125. | Tool | Description |
  126. |---|---|
  127. | `get_courses` | Retrieve available Quera courses. |
  128. | `get_assignments` | Retrieve assignments for a course. |
  129. | `get_assignment_details` | Retrieve detailed information about an assignment. |
  130. | `get_problems` | List problems belonging to an assignment. |
  131. | `get_problem` | Retrieve a problem statement and its content. |
  132. | `get_problem_metadata` | Retrieve problem metadata. |
  133. | `submit_code_answer` | Submit source code for a problem. |
  134. | `get_submissions` | Retrieve submission history for a problem. |
  135. | `get_submission_result` | Retrieve the result of a submission. |
  136. | `set_submission_final` | Mark a submission as final. |
  137. | `get_current_time` | Retrieve the current time. |
  138. Tool availability and returned information depend on the underlying Quera Client implementation and Quera's responses.
  139. ---
  140. # Connecting to AI Agents
  141. QueraMCP communicates through **MCP over STDIO**. Most local MCP clients can launch it directly using the Python interpreter inside its virtual environment.
  142. The examples below assume the repository is located at:
  143. ```text
  144. /home/YOUR_USERNAME/QueraMCP
  145. ```
  146. Replace this path with the actual absolute path on your machine.
  147. > **Important:** Use the Python executable inside `.venv`. This ensures the MCP server uses the dependencies installed for QueraMCP rather than relying on your system Python.
  148. ## 1. OpenCode
  149. [OpenCode](https://opencode.ai/) supports local MCP servers through its configuration file.
  150. Open your OpenCode configuration file:
  151. ```bash
  152. mkdir -p ~/.config/opencode
  153. ```
  154. Depending on your setup, configure either your global OpenCode configuration or your project's `opencode.json`.
  155. Add the following configuration:
  156. ```json
  157. {
  158. "$schema": "https://opencode.ai/config.json",
  159. "mcp": {
  160. "servers": {
  161. "QueraMCP": {
  162. "type": "local",
  163. "command": [
  164. "/home/YOUR_USERNAME/QueraMCP/.venv/bin/python",
  165. "/home/YOUR_USERNAME/QueraMCP/server.py"
  166. ],
  167. "cwd": "/home/YOUR_USERNAME/QueraMCP",
  168. "timeout": {
  169. "startup": 45000,
  170. "catalog": 30000,
  171. "execution": 600000
  172. },
  173. "codemode": false
  174. }
  175. }
  176. }
  177. }
  178. ```
  179. If you already have an OpenCode configuration, merge the `mcp` section into it instead of replacing the entire file.
  180. ### Verify the connection
  181. ```bash
  182. opencode mcp list
  183. ```
  184. Launch OpenCode and inspect the available MCP connections:
  185. ```text
  186. /mcps
  187. ```
  188. You should see `QueraMCP` listed as connected.
  189. With `codemode` disabled, individual tools should be exposed directly, with names such as:
  190. ```text
  191. QueraMCP_get_courses
  192. QueraMCP_get_assignments
  193. QueraMCP_get_problem
  194. QueraMCP_submit_code_answer
  195. ```
  196. ---
  197. ## 2. Claude Desktop
  198. [Claude Desktop](https://claude.ai/download) supports local MCP servers through its configuration file.
  199. Open the Claude Desktop configuration file.
  200. **Linux**
  201. ```text
  202. ~/.config/Claude/claude_desktop_config.json
  203. ```
  204. **macOS**
  205. ```text
  206. ~/Library/Application Support/Claude/claude_desktop_config.json
  207. ```
  208. **Windows**
  209. ```text
  210. %APPDATA%\Claude\claude_desktop_config.json
  211. ```
  212. Add:
  213. ```json
  214. {
  215. "mcpServers": {
  216. "QueraMCP": {
  217. "command": "/home/YOUR_USERNAME/QueraMCP/.venv/bin/python",
  218. "args": [
  219. "/home/YOUR_USERNAME/QueraMCP/server.py"
  220. ],
  221. "env": {
  222. "PYTHONUNBUFFERED": "1"
  223. }
  224. }
  225. }
  226. }
  227. ```
  228. Save the configuration and restart Claude Desktop.
  229. Claude Desktop should start QueraMCP automatically when it needs the server.
  230. ---
  231. ## 3. Claude Code
  232. [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) supports MCP servers through its built-in MCP management commands.
  233. Register QueraMCP:
  234. ```bash
  235. claude mcp add --transport stdio QueraMCP \
  236. -- /home/YOUR_USERNAME/QueraMCP/.venv/bin/python \
  237. /home/YOUR_USERNAME/QueraMCP/server.py
  238. ```
  239. Inspect the registered servers:
  240. ```bash
  241. claude mcp list
  242. ```
  243. You can also inspect MCP connections from inside a Claude Code session using:
  244. ```text
  245. /mcp
  246. ```
  247. ---
  248. ## 4. Cursor
  249. [Cursor](https://cursor.com/) supports MCP servers through project-level or global configuration.
  250. For project-level configuration, create:
  251. ```text
  252. .cursor/mcp.json
  253. ```
  254. Add:
  255. ```json
  256. {
  257. "mcpServers": {
  258. "QueraMCP": {
  259. "command": "/home/YOUR_USERNAME/QueraMCP/.venv/bin/python",
  260. "args": [
  261. "/home/YOUR_USERNAME/QueraMCP/server.py"
  262. ],
  263. "env": {
  264. "PYTHONUNBUFFERED": "1"
  265. }
  266. }
  267. }
  268. }
  269. ```
  270. Restart Cursor or reload the MCP configuration.
  271. You should then be able to use QueraMCP tools from Cursor's AI agent.
  272. ---
  273. ## 5. Visual Studio Code (GitHub Copilot)
  274. [Visual Studio Code](https://code.visualstudio.com/) supports MCP servers through workspace configuration.
  275. Create:
  276. ```text
  277. .vscode/mcp.json
  278. ```
  279. Add:
  280. ```json
  281. {
  282. "servers": {
  283. "QueraMCP": {
  284. "type": "stdio",
  285. "command": "/home/YOUR_USERNAME/QueraMCP/.venv/bin/python",
  286. "args": [
  287. "/home/YOUR_USERNAME/QueraMCP/server.py"
  288. ],
  289. "env": {
  290. "PYTHONUNBUFFERED": "1"
  291. }
  292. }
  293. }
  294. }
  295. ```
  296. Open the Command Palette and search for:
  297. ```text
  298. MCP: List Servers
  299. ```
  300. Select `QueraMCP` and start the server.
  301. You can now use its tools from compatible GitHub Copilot agent sessions.
  302. ---
  303. ## 6. Windsurf
  304. [Windsurf](https://windsurf.com/) supports MCP through its MCP configuration file.
  305. Open:
  306. ```text
  307. ~/.codeium/windsurf/mcp_config.json
  308. ```
  309. Add:
  310. ```json
  311. {
  312. "mcpServers": {
  313. "QueraMCP": {
  314. "command": "/home/YOUR_USERNAME/QueraMCP/.venv/bin/python",
  315. "args": [
  316. "/home/YOUR_USERNAME/QueraMCP/server.py"
  317. ],
  318. "env": {
  319. "PYTHONUNBUFFERED": "1"
  320. }
  321. }
  322. }
  323. }
  324. ```
  325. Save the file and restart or reload Windsurf.
  326. ---
  327. ## 7. Cline
  328. [Cline](https://cline.bot/) supports external MCP servers.
  329. Open the MCP Servers configuration in Cline and edit its MCP settings.
  330. Add:
  331. ```json
  332. {
  333. "mcpServers": {
  334. "QueraMCP": {
  335. "command": "/home/YOUR_USERNAME/QueraMCP/.venv/bin/python",
  336. "args": [
  337. "/home/YOUR_USERNAME/QueraMCP/server.py"
  338. ],
  339. "env": {
  340. "PYTHONUNBUFFERED": "1"
  341. },
  342. "disabled": false,
  343. "autoApprove": []
  344. }
  345. }
  346. }
  347. ```
  348. Save the configuration and enable the server.
  349. ---
  350. ## 8. Gemini CLI
  351. [Gemini CLI](https://github.com/google-gemini/gemini-cli) supports MCP servers through its settings configuration.
  352. Open or create:
  353. ```text
  354. ~/.gemini/settings.json
  355. ```
  356. Add:
  357. ```json
  358. {
  359. "mcpServers": {
  360. "QueraMCP": {
  361. "command": "/home/YOUR_USERNAME/QueraMCP/.venv/bin/python",
  362. "args": [
  363. "/home/YOUR_USERNAME/QueraMCP/server.py"
  364. ],
  365. "env": {
  366. "PYTHONUNBUFFERED": "1"
  367. }
  368. }
  369. }
  370. }
  371. ```
  372. Restart Gemini CLI to load the server.
  373. ---
  374. ## 9. OpenAI Codex
  375. [OpenAI Codex](https://developers.openai.com/codex/) supports MCP servers through its configuration.
  376. For a local STDIO server, add the following to:
  377. ```text
  378. ~/.codex/config.toml
  379. ```
  380. ```toml
  381. [mcp_servers.QueraMCP]
  382. command = "/home/YOUR_USERNAME/QueraMCP/.venv/bin/python"
  383. args = ["/home/YOUR_USERNAME/QueraMCP/server.py"]
  384. ```
  385. Restart Codex or reload its MCP configuration.
  386. ---
  387. ## 10. Other MCP-compatible applications
  388. The configurations above use the standard local STDIO pattern.
  389. For another MCP client, the essential configuration is generally:
  390. ```json
  391. {
  392. "command": "/absolute/path/to/QueraMCP/.venv/bin/python",
  393. "args": [
  394. "/absolute/path/to/QueraMCP/server.py"
  395. ]
  396. }
  397. ```
  398. The exact configuration structure depends on the application.
  399. Check your client's MCP documentation for its expected configuration format.
  400. ### What about ChatGPT?
  401. ChatGPT's custom MCP connections use a remotely accessible MCP endpoint rather than launching a local STDIO process directly.
  402. The current QueraMCP setup is a local STDIO server. Connecting it to ChatGPT therefore requires an appropriate remote transport and deployment setup. Do not expose your local Quera credentials or an unauthenticated server to the public internet.
  403. ---
  404. # Agent Instructions
  405. MCP tools provide capabilities. Agent instructions tell an AI assistant how to use those capabilities responsibly.
  406. QueraMCP can be used alongside an `AGENTS.md` file containing project-specific instructions.
  407. For example:
  408. ```text
  409. QueraMCP/
  410. ├── server.py
  411. ├── QueraClient.py
  412. ├── RecaptchaSolver.py
  413. ├── requirements.txt
  414. ├── .env
  415. ├── AGENTS.md
  416. └── .venv/
  417. ```
  418. An `AGENTS.md` file can describe:
  419. - How to discover courses and assignments.
  420. - How to retrieve and understand problem statements.
  421. - How to inspect submission history.
  422. - How to interpret evaluation results.
  423. - How to review code before submitting it.
  424. - How to handle failed submissions.
  425. - When explicit user authorization is required.
  426. For clients that support project instructions, place `AGENTS.md` in the workspace root or configure the client to load it.
  427. **Important:** MCP server instructions and agent instruction files are separate mechanisms. A client may support one, both, or neither.
  428. ---
  429. # Security
  430. QueraMCP interacts with a real Quera account. Treat its tools as account-access capabilities, not merely read-only utilities.
  431. ### Credential management
  432. - Store credentials in `.env`.
  433. - Never hardcode credentials in source code.
  434. - Never commit `.env` to Git.
  435. - Never print passwords, authentication cookies, or session tokens.
  436. - Use a dedicated and appropriately secured environment.
  437. ### Protect your `.env`
  438. Your `.gitignore` should include:
  439. ```gitignore
  440. .env
  441. .venv/
  442. __pycache__/
  443. *.py[cod]
  444. quera.log
  445. ```
  446. ### Submission authorization
  447. Code submission and finalization can modify your Quera account.
  448. An AI agent should:
  449. 1. Present the code it intends to submit.
  450. 2. Explain what it is about to do.
  451. 3. Obtain explicit authorization before submitting.
  452. 4. Inspect the result after submission.
  453. 5. Obtain authorization again before submitting a revised solution.
  454. Marking a submission as final should also require explicit authorization.
  455. Do not configure an AI agent to submit code or finalize submissions without appropriate user oversight.
  456. ### Local execution
  457. The recommended setup runs QueraMCP locally through STDIO. This avoids exposing a network-accessible endpoint unnecessarily.
  458. Remember that any MCP client connected to QueraMCP may be able to invoke the tools exposed by the server. Review the available tools and the client's approval settings before using it.
  459. ---
  460. # Troubleshooting
  461. ### `KeyError: 'QUERA_USERNAME'`
  462. Make sure:
  463. - Your `.env` file exists.
  464. - It contains `QUERA_USERNAME` and `QUERA_PASSWORD`.
  465. - `load_dotenv()` runs before the client is initialized.
  466. - Your `QueraClient` constructor does not access `os.environ[...]` in default argument expressions.
  467. Prefer:
  468. ```python
  469. def __init__(
  470. self,
  471. identifier: str | None = None,
  472. credential: str | None = None
  473. ):
  474. identifier = identifier or os.getenv("QUERA_USERNAME")
  475. credential = credential or os.getenv("QUERA_PASSWORD")
  476. ```
  477. ### `ModuleNotFoundError`
  478. Activate the virtual environment and install dependencies:
  479. ```bash
  480. source .venv/bin/activate
  481. pip install -r requirements.txt
  482. ```
  483. Make sure your MCP client uses:
  484. ```text
  485. /path/to/QueraMCP/.venv/bin/python
  486. ```
  487. rather than the system Python interpreter.
  488. ### MCP server fails to start
  489. Run the server manually:
  490. ```bash
  491. cd /path/to/QueraMCP
  492. source .venv/bin/activate
  493. python server.py
  494. ```
  495. Inspect the terminal output for missing dependencies, configuration errors, or authentication problems.
  496. ### MCP tools are not visible
  497. Check:
  498. 1. Whether the server is registered in your AI client's MCP configuration.
  499. 2. Whether the Python executable points to the correct virtual environment.
  500. 3. Whether the server script path is correct.
  501. 4. Whether the client has restarted or reloaded its MCP configuration.
  502. 5. Whether the server can start independently.
  503. ### Authentication problems
  504. Check your Quera credentials and the browser-related dependencies used by your authentication implementation. CAPTCHA and login behavior may change independently of QueraMCP.
  505. ---
  506. # License
  507. Distributed under the MIT License. See [`LICENSE`](LICENSE) for more information.
  508. ---
  509. <div align="center">
  510. ### Built for developers. Designed for AI agents.
  511. **QueraMCP — Bringing Quera into your AI workflow**
  512. Amirreza Mirjalily
  513. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.