OpenSTEM

openstem-mcp

English: README.en.md

이공계 공부를 돕는 MCP 서버. 이미 쓰고 있는 AI(Claude 등)에 붙이면 학술 그림을 그리고, 풀이를 검산하고, 강의 자료(PDF·한글 파일)를 읽어 예상문제·슬라이드·암기 카드·실험 보고서를 만들 수 있다. 서버는 AI를 따로 부르지 않고 그리기·계산만 하므로 추가 구독이나 API 키가 필요 없다. 모든 작업은 내 PC에서 돈다(단, LaTeX 패키지는 처음 쓸 때 tectonic 번들 서버에서 받아 온다. 문서 내용은 보내지 않는다. → PRIVACY.md).

Your AI. Your Tools. Your Freedom. 배움은 열려 있어야 한다. 쓰고 싶은 AI 모델과 필요한 도구 사이에서 하나를 고르지 않아도 되게 만든다. → OpenSTEM 선언문

| | "$\sin^2 x = \frac{1-\cos 2x}{2}$ 맞아?" → matches: true "$(x+1)^2 = x^2+1$?" → matches: false, 반례 $x=-2.03$ "$\int x e^x dx$" → $(x-1)e^x$ |

설치

원클릭 (Claude Desktop)

1. 받기 — 릴리스 페이지에서 openstem-<버전>.mcpb 파일을 내려받는다.
2. 더블클릭 — 받은 파일을 더블클릭하면 Claude Desktop에 확장 설치 화면이 열린다. 설치를 누른다(안 열리면 Claude Desktop 설정의 확장 화면에 파일을 끌어다 놓는다).
3. 폴더 고르기 — 결과물 폴더(기본: 문서/OpenSTEM)를 확인하고, 원하면 자료 폴더(AI가 읽을 PDF·한글 파일을 넣는 곳)와 학교 이름·LMS 토큰을 넣은 뒤 켠다(아래 "학교 LMS 연결").

처음 켤 때 파이썬 패키지, LaTeX 엔진(tectonic), TeX 패키지(합쳐 약 500 MB)를 내려받느라 몇 분 걸린다. 그동안 그림·PDF 툴은 "준비 중"이라고 답하니 잠시 뒤 다시 시키면 된다.

Claude Code 플러그인 (사용 지침 포함)

Claude Code에서 아래 한 줄이면 서버와 함께 사용 지침(스킬 6개: 풀이 검산, 그림, 시험 대비, 실험 보고서, 발표·문서, 학교 LMS)이 설치된다. 켤 때 결과물 폴더·자료 폴더·학교 LMS 설정을 물어본다(모두 선택).

/plugin install openstem --marketplace kimi94279-glitch/openstem-mcp

직접 설치 (Claude Code·설정 파일)

1. uv 설치 — 파이썬 프로그램을 내려받아 실행해 주는 도구다.

• Windows (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
• macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

2. 미리 준비(선택) — 그림·PDF를 만드는 LaTeX 엔진(tectonic)은 처음 켤 때 서버가 공식 릴리스를 받아 해시를 확인한 뒤 설치한다. 터미널에서 한 번 실행해 두면 AI 앱에서 처음 쓸 때 기다리지 않는다(처음 한 번만, 약 300 MB, 3~5분):

uvx openstem-mcp --warmup

자동 설치를 원하지 않으면 환경변수 OPENSTEM_NO_DOWNLOAD=1을 두고 tectonic을 직접 설치한다: Windows는 tectonic 릴리스의 x86_64-pc-windows-msvc.zip에서 tectonic.exe를 PATH 폴더에, macOS는 brew install tectonic, Linux는 curl --proto '=https' --tlsv1.2 -fsSL https://drop-sh.fullyjustified.net | sh 후 mv tectonic ~/.local/bin/.

3. AI 앱에 연결

Claude Desktop: 앱을 완전히 종료한 뒤(트레이 아이콘 → 종료) 설정 파일 claude_desktop_config.json에 아래를 넣고 다시 켠다. (Windows %APPDATA%\Claude\, macOS ~/Library/Application Support/Claude/. 앱이 켜진 채로 고치면 앱이 덮어쓴다.)

{

"mcpServers": { "openstem": { "command": "uvx", "args": ["openstem-mcp"] } } }

Claude Code:

uvx openstem-mcp --warmup      # 먼저 터미널에서 한 번(패키지 설치 + tectonic·TeX 준비)

claude mcp add openstem -- uvx openstem-mcp

첫 uvx openstem-mcp는 파이썬 패키지(약 200 MB)를 설치하느라 Claude Code의 서버 시작 제한(기본 30초)을 넘겨 연결이 실패할 수 있다. 위처럼 터미널에서 --warmup을 먼저 하거나, 제한을 늘려 띄운다(예: MCP_TIMEOUT=120000 claude, 밀리초).

설정을 더 하고 싶으면(선택) 같은 자리에 env와 args를 넣는다. 예: 결과물 폴더 바꾸기, tectonic 위치 지정, LaTeX 입력 검산 켜기.

{

"mcpServers": { "openstem": { "command": "uvx", "args": ["--from", "openstem-mcp[latex]", "openstem-mcp"], "env": { "OPENSTEM_OUTPUT_DIR": "D:\\공부\\그림", "OPENSTEM_TECTONIC": "C:\\Users\\<이름>\\.local\\bin\\tectonic.exe" } } } }

macOS에서 앱이 uvx나 tectonic을 못 찾으면(앱은 터미널과 PATH가 다를 수 있다) 터미널에서 which uvx, which tectonic으로 나온 전체 경로를 command와 OPENSTEM_TECTONIC에 넣는다.

ChatGPT에서 쓰기

ChatGPT는 인터넷의 HTTPS 주소로만 MCP 서버에 붙는다. 그래서 내 PC에서 서버를 HTTP 모드로 켜고, cloudflared로 임시 HTTPS 주소를 연다.

확인하지 못한 것(2026년 11월)

- 사용자 지정 MCP 서버는 OpenAI 도움말 기준 Business·Enterprise·Edu 요금제(웹) 에서 쓸 수 있다. Plus 등 개인 요금제에서 되는지는 확인하지 못했다. 요금제에 따라 메뉴가 없거나 읽기 툴만 될 수 있다.

- 툴 결과에 붙인 그림 미리보기(PNG)가 ChatGPT 모델에 실제로 전달되는지 확인하지 못했다. 그림 파일은 이 PC의 결과물 폴더에 저장되니 거기서 연다.

- 실제 ChatGPT·cloudflared 연결 시험도 아직이다.

1. cloudflared 설치(한 번만): Windows winget install --id Cloudflare.cloudflared, macOS brew install cloudflared, Linux는 Cloudflare 문서의 패키지 설치 안내
2. 서버 켜기: uvx openstem-mcp --http --tunnel → 터미널에 ChatGPT 커넥터 URL: https://….trycloudflare.com/<비밀 키>/mcp가 나온다
3. ChatGPT 설정 → 앱(또는 커넥터) → 고급 설정에서 개발자 모드를 켜고, 사용자 지정 MCP 서버(앱 만들기)에 위 URL을 붙여 넣은 뒤 인증은 "없음"을 고른다(메뉴 이름은 바뀔 수 있다)

• URL 가운데의 긴 문자열이 비밀 키다. 키가 틀린 요청은 모두 404다. 남에게 보여 주지 말고, 새어 나갔으면 --new-secret으로 바꾼다.
• 임시 터널 주소는 켤 때마다 바뀌므로 ChatGPT에 새 URL을 다시 넣어야 한다(비밀 키는 그대로).
• 터미널 창을 닫거나 PC가 잠들면 연결이 끊긴다. 그림·문서는 서버를 켠 이 PC의 결과물 폴더에 저장된다.
• 터널 없이 이 PC 안에서만 쓰려면 uvx openstem-mcp --http → http://127.0.0.1:8765/<비밀 키>/mcp(또는 /mcp에 헤더 Authorization: Bearer <키>). 포트는 --port로 바꾼다.

이렇게 쓴다

AI에게 평소처럼 말하면 된다.

• "RC 직렬회로 그려줘", "빗면 위 물체의 자유물체도 그려줘", "PID 제어 블록도 그려줘"
• "y = sin(x)·e^(−x/5) 그래프 그려줘", "아스피린 구조식 보여줘"
• "이 적분 풀고 단계마다 검산해줘", "y'' + 3y' + 2y = sin x 풀어줘", "이 행렬 고윳값 구해줘"
• "이 답 단위 맞아?", "72 km/h를 m/s로"
• "자료 폴더의 3장 PDF로 예상문제 10개랑 해설 만들어줘"
• "이 측정값으로 그래프 그리고 기울기 구해서 실험 보고서 써줘"
• "이 단원 내용으로 A4 한 장 치트시트 PDF", "발표 슬라이드 10장", "암기 카드 20장 만들어줘"

결과물은 ~/OpenSTEM/(Windows는 C:\Users\<이름>\OpenSTEM\)에 쌓인다. 다른 곳에 두려면 환경변수 OPENSTEM_OUTPUT_DIR을 설정한다.

자료 폴더: 강의 자료·기출문제·공지(PDF, 한글 HWP·HWPX, 워드, 파워포인트, 엑셀)를 ~/OpenSTEM/자료/에 넣어 두면 AI가 이름으로 골라 읽는다. 이 폴더(와 결과물 폴더) 밖 파일은 열지 않는다. 다른 곳을 쓰려면 환경변수 OPENSTEM_INPUT_DIR을 설정한다. 사진이나 몇 개 안 되는 파일은 채팅에 바로 첨부해도 된다.

AI 앱의 프롬프트 메뉴에서 바로 고를 수도 있다.

학교 LMS 연결 (선택, 읽기 전용)

과목·다가오는 마감·공지·강의 자료를 AI가 읽어 온다. 자료 파일은 자료 폴더의 LMS/과목명/으로 받아 바로 읽는다. "일반물리 자료 다 받아 줘"라고 하면 과목 자료를 한 번에 받고, 다음부터는 새로 올라오거나 바뀐 파일만 받는다. 제출·글쓰기는 하지 않고, 비밀번호는 받지 않는다.

1. 학교 이름 넣기 — 확장 설정의 학교 이름에 학교 이름만 넣으면 LMS 주소는 자동으로 찾는다. 줄임말도 된다(성대, 서울대, KAIST, 코리아텍). Claude Code나 설정 파일로 쓸 때는 환경변수 OPENSTEM_LMS_SCHOOL을 쓴다.

claude mcp add openstem -e OPENSTEM_LMS_SCHOOL=성균관대 -e OPENSTEM_LMS_TOKEN=<토큰> -- uvx openstem-mcp

AI에게 "LMS 지원 학교 목록 보여 줘"라고 하면 목록과 학교별 연결 방법을 알려 준다.

2. 토큰 만들기 (LMS 웹사이트에서 직접)

만든 토큰을 확장 설정의 LMS 액세스 토큰(또는 OPENSTEM_LMS_TOKEN)에 넣고 앱을 다시 켠다. 토큰은 학교 LMS 주소로만 보낸다.

3. 토큰을 만들 수 없을 때: 캘린더 주소 (마감만) — 학교가 학생 토큰을 막았거나 모바일 서비스가 꺼져 있으면(연세대 LearnUs, 동국대, 한국기술교육대) LMS 캘린더의 구독 주소로 과제 마감만 읽을 수 있다.

주소를 확장 설정의 LMS 캘린더 주소(또는 OPENSTEM_LMS_CALENDAR_URL)에 넣는다. 이 주소만 있으면 누구나 내 일정을 볼 수 있으니 비밀번호처럼 다룬다(도구도 결과에 싣지 않는다). 토큰과 캘린더 주소를 둘 다 넣으면 토큰을 먼저 쓰고 캘린더에만 있는 일정을 덧붙인다.

연결 시험 대상 (2026년 11월, 공개 페이지 조사)

실제 학교 LMS로 확인한 곳: 아직 없음(고려대 확인 예정). 아래 표는 각 학교 공개 페이지로 LMS 종류를 조사해 주소를 넣어 둔 목록이고, 기능은 가짜 서버(tests/fake_lms.py)로만 시험했다. 내 학교에서 되는지(또는 안 되는지) 학교 LMS 확인 보고로 알려 주면 "확인한 곳"으로 옮긴다.

\* 모바일 서비스가 꺼져 있어 토큰 대신 캘린더 주소를 쓴다.

• LearningX 학교는 학생이 아는 주소(예: icampus.skku.edu)와 실제 API 주소(canvas.skku.edu)가 다르다. 학교 이름만 넣으면 알아서 맞는 주소를 쓴다.
• 고려대·중앙대·경희대 등 일부는 학생이 토큰을 만들 수 있는지 확인하지 못했다. 안 되면 캘린더 주소를 쓴다.
• 토큰 정책: Canvas 공식 API 정책은 여러 사용자가 쓰는 앱이 사용자에게 액세스 토큰을 직접 만들게 하는 대신 OAuth를 쓰도록 요구한다. 이 도구는 각자 자기 PC에서 자기 토큰으로 자기 데이터만 읽지만, 학교가 이 방식을 허용하는지는 학교 정책에 달려 있다. 학교는 학생 토큰 발급을 막거나 만료 기간을 둘 수 있고, 그러면 토큰이 갑자기 안 될 수 있다(그때는 캘린더 주소를 쓴다). 학교 이용 규정을 먼저 확인한다.
• 지원 안 되는 학교: Blackboard는 캘린더에 iCal 링크가 있으면 마감만 읽을 수 있다(확인 못 함). 그 밖에는 강의 자료를 직접 내려받아 자료 폴더에 넣고 AI에게 읽어 달라고 하면 된다.
• 목록에 없는 학교도 Canvas나 Moodle이면 LMS 주소 직접 지정(OPENSTEM_LMS_URL)과 토큰으로 쓸 수 있다.

툴

자주 묻는 것

• 무엇이 문제인지 모르겠다 — 터미널에서 uvx openstem-mcp --doctor를 실행하면 tectonic·TeX 준비·네트워크·폴더 권한·계산 작업자를 점검하고, 끝에 이슈에 붙여 넣을 요약(홈 폴더·비밀 값은 가린 것)을 출력한다. 네트워크 점검을 빼려면 --offline, JSON은 --json.
• 업데이트하고 싶다 — 원클릭(.mcpb): 새 .mcpb를 받아 다시 설치한다(설정은 남는다). uvx로 쓰는 경우: AI 앱을 완전히 끄고 uv cache clean openstem-mcp를 실행한 뒤 다시 켜면 최신판을 받는다. 버전은 uvx openstem-mcp --version으로 확인한다.
• 완전히 지우고 싶다 — Claude Desktop 확장 화면에서 제거하거나 설정 파일에서 openstem 항목을 지운 뒤, uv cache clean openstem-mcp와 아래 폴더를 지운다. 결과물 폴더(기본 ~/OpenSTEM)는 사용자 파일이라 직접 판단한다.
• tectonic·TeX 패키지(약 300 MB): Windows %LOCALAPPDATA%\openstem·%LOCALAPPDATA%\TectonicProject, macOS ~/Library/Caches/openstem·~/Library/Caches/TectonicProject.Tectonic, Linux ~/.cache/openstem·~/.cache/tectonic(예전 tectonic은 Tectonic)
• HTTP 모드 비밀 키(http-secret)가 든 설정 폴더: Windows %APPDATA%\openstem, macOS ~/Library/Application Support/openstem, Linux ~/.config/openstem
• 처음 그림이 안 나오고 "준비 중"이라고 한다 — 첫 실행 때 TeX 패키지를 받는 중이다(3~5분, 한 번만). 설치 2단계의 --warmup을 미리 해 두면 생기지 않는다.
• "tectonic을 찾을 수 없다" / "자동 설치 실패" — 서버가 tectonic을 받지 못한 경우다(인터넷·방화벽, 또는 Windows ARM처럼 공식 파일이 없는 PC). 직접 설치 2단계의 안내대로 tectonic을 설치하고 AI 앱을 다시 켠다. PATH 밖에 두었다면 위 설정 예시처럼 OPENSTEM_TECTONIC에 실행 파일 경로를 넣는다.
• "TeX 패키지를 내려받지 못했다" — 처음 쓰는 패키지는 tectonic 서버에서 받아 온다. 인터넷 연결이나 학교·회사 방화벽을 확인한다.
• LaTeX로 쓴 식을 검산하고 싶다 — verify_math의 latex=true는 선택 기능이다. 위 설정 예시처럼 openstem-mcp[latex]로 실행하면 켜진다. 없어도 AI가 sympy 문법으로 바꿔 보낸다.
• 물리 공식 검산이 "틀림"으로 나온다 — 변수를 음수일 수도 있는 실수로 보면 √(m²v²) = mv 같은 변형이 틀린 게 맞다. 물리량은 AI가 assume="positive"로 검산하게 되어 있다.
• 설치가 안 되는 컴퓨터 — Windows ARM(Snapdragon 등)은 pandoc 패키지가 없어 지원하지 않는다.
• 안전한가 — 임의 코드를 실행하는 툴은 없다. LaTeX·수식·SMILES는 별도 프로세스에서 시간 제한을 두고 처리하고, 파일을 읽거나 쓰는 TeX 명령과 결과물 폴더 밖·인터넷 그림은 컴파일 전에 검사해 막는다. Linux(bubblewrap)와 macOS(sandbox-exec)에서는 이 처리를 운영체제 샌드박스 안에서 돌려 검사를 빠져나가도 홈 폴더의 파일을 읽거나 작업 폴더 밖에 쓰지 못하게 한다(Windows는 아직 없음). 지키는 범위, 알려진 한계, 취약점을 알리는 방법은 SECURITY.md에 있다.

개인정보

만든 사람은 서버를 운영하지 않고 어떤 데이터도 모으지 않는다(분석·추적 없음). 네트워크 연결은 설치(PyPI), tectonic 자동 설치(공식 GitHub 릴리스, 해시 확인), TeX 패키지(tectonic 서버), 설정한 경우 학교 LMS뿐이다. 자세한 내용: [PRIVACY.md](PR