ShioriSAFE
Open-source AI study companion — Google Classroom sync, Gemini AI plans, SRS flashcards, GPA predictor, AI quiz, MCP server for Claude Code. Try demo at shiori-v1.vercel.app
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
An AI study companion for students who actually care about their grades. Quizzes, flashcards, grade tracking, and study planning in one app — bring your own free Gemini API key, no subscription needed.
[Try the demo](https://shiori-v1.vercel.app/demo) — no account or API key required.
Features
- AI quiz generator and spaced-repetition flashcards from your notes
- Weighted grade calculator with GPA prediction
- Assignment manager with due dates and priorities
- Markdown notes with live preview
- Pomodoro focus mode linked to tasks
- Study plans generated day-by-day from your syllabus
- Habit tracker, XP/leveling, and a friends leaderboard
- Keyboard-driven navigation (
g h,g a,g n,g q...)
Getting started
Fastest: just open the demo.
Deploy your own:
[](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fkaorii-ako%2FShiori-v1&env=VITESUPABASEURL,VITESUPABASEANON_KEY&envDescription=Required%20for%20user%20accounts&project-name=shiori&repository-name=Shiori-v1)
Self-host:
git clone https://github.com/kaorii-ako/Shiori-v1.git cd Shiori-v1 cp .env.example .env # add your Supabase URL + anon key npm install npm run dev
You'll need a free Supabase project (URL + anon key from Settings → API) and, optionally, a free Gemini API key for the AI features.
Stack
React + Vite + Zustand on the frontend, Supabase for auth and data, Gemini 1.5 Flash for AI (called client-side with your own key), deployed on Vercel.
Structure
Shiori-v1/ ├── client/ React + Vite frontend ├── server/ Express backend (Stripe webhooks only) ├── extension/ Chrome MV3 extension └── supabase/ DB schema + setup
Contributing
PRs welcome. Start with [good first issues](https://github.com/kaorii-ako/Shiori-v1/issues?q=label%3A%22good+
0275bf55a869OBSERVED · 2026-10-08Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add server --env APPWRITE_API_KEY=${APPWRITE_API_KEY} --env GEMINI_API_KEY=${GEMINI_API_KEY} --env GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET} --env GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET} -- npx -y [email protected]{
"mcpServers": {
"server": {
"command": "npx",
"args": [
"-y",
"[email protected]"
],
"env": {
"APPWRITE_API_KEY": "${APPWRITE_API_KEY}",
"GEMINI_API_KEY": "${GEMINI_API_KEY}",
"GITHUB_CLIENT_SECRET": "${GITHUB_CLIENT_SECRET}",
"GOOGLE_CLIENT_SECRET": "${GOOGLE_CLIENT_SECRET}"
}
}
}
}Exposed tools (8)
7 read · 1 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
add_assignment | write | Add a new assignment to Shiori. |
get_assignments | read | List your upcoming assignments. Optionally filter by course or status. |
get_flashcard_decks | read | List your flashcard decks and review status. |
get_grades | read | Show your current GPA and grades per course. |
get_notes | read | List and read your course notes. |
get_study_plan | read | Generate a prioritized study plan for today or the next N days based on upcoming deadlines. |
get_study_summary | read | Get a full summary of your current academic status — assignments, grades, habits, and upcoming events. |
predict_grade | read | Calculate the score you need on your final exam to achieve a target grade in a course. |
Trust audit
SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | PASS |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (4 observation(s))
- Network
- declared (8 observation(s))
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (10)
.wakatime-project
const CREDENTIALS_PATH = path.join(__dirname, '../../.env')
const tokensPath = path.join(__dirname, '../../tokens.json')
const tokensPath = path.join(__dirname, '../../tokens.json')
const tokensPath = path.join(__dirname, '../../tokens.json')
return JSON.parse(decodeURIComponent(escape(atob(b64))))
@mlc-ai/web-llm, @react-three/drei, @react-three/fiber, @supabase/supabase-js, animejs, axios, canvas-confetti, framer-motion
@modelcontextprotocol/sdk, zod
@supabase/supabase-js, dotenv, googleapis, stripe, concurrently
cors, dotenv, express, express-validator, googleapis, uuid, @google/generative-ai
Gates applied: no_behavioural_pass.
0275bf55a869full audit observations/trust-audit/mcp-server/kaorii-ako__shiori.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-08 | 0275bf55a869 | SAFE | B | 89 | first audit |
Questions
What is the Shiori MCP server?
Open-source AI study companion — Google Classroom sync, Gemini AI plans, SRS flashcards, GPA predictor, AI quiz, MCP server for Claude Code. Try demo at shiori-v1.vercel.app
What tools does Shiori expose?
8 in total: 7 read-only, 1 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is Shiori safe to connect to an agent?
The audit found nothing in the source that contradicts what it says it does, and graded it B (89/100). Grade A is held back for packages that have also passed a sandboxed behavioural run, which is why a clean server reads B.
What credentials does Shiori need?
It reads APPWRITE_API_KEY, GEMINI_API_KEY, GITHUB_CLIENT_SECRET, GOOGLE_CLIENT_SECRET, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET and SUPABASE_SERVICE_ROLE_KEY from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does Shiori run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as server at 1.0.0.
How current is this page?
The grade is for one exact copy of the source (0275bf55a869), read on 2026-10-08. The repository is watched and re-audited when it changes.