k-exaone-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@k-exaone-mcp ask exaone to review ./src/auth.ts and cross-check your answer"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
k-exaone-mcp
Claude, Gemini(Antigravity), Codex, Cline 같은 MCP 클라이언트가 LG AI연구원의 K-EXAONE 2.5에게 일을 맡기고 답을 받아 오게 하는 MCP 서버입니다. Hermes나 OpenCode 같은 별도 에이전트 CLI를 설치하지 않아도 되고, 각자 자기 EXAONE API 키만 넣으면 바로 쓸 수 있습니다.
나 ─▶ Claude / Gemini / Codex ─(ask_exaone)─▶ k-exaone-mcp ─▶ EXAONE API (K-EXAONE 2.5)
◀──────── 답변 + 토큰 사용량 + 남은 호출 한도 ◀──────────LG AI연구원의 공식 프로젝트가 아닌 개인 오픈소스입니다. EXAONE은 LG AI연구원의 상표입니다.
할 수 있는 일
작업 위임과 교차 검토: "이 설계안을 엑사원한테 검토받아 줘", "엑사원 답이랑 비교해 줘"
로컬 파일 첨부:
files에 경로를 넘기면 서버가 직접 파일을 읽어 EXAONE에게 보냅니다. 파일 내용이 호출한 AI(Claude, Gemini, Codex 등)의 컨텍스트를 거치지 않으므로 그쪽 토큰을 아낄 수 있습니다.이어서 대화: 답변 끝의
conversation_id를 넘기면 이전 대화와 추론을 이어 갑니다(preserve_thinking).추론 강도 선택:
low/medium/high/max사용량 표시: 모든 답변 끝에 토큰 사용량과 남은 호출 한도(초·분·일)를 붙입니다.
exaone_status도구로 누적 사용량을 볼 수 있습니다.호출 한도 자동 처리: 초당 한도(429)에 걸리면 잠깐 기다렸다가 다시 보냅니다. 일일 한도를 다 썼으면 그 사실을 바로 알려 줍니다.
Related MCP server: MultiAgents-MCP
빠른 시작
1. API 키 발급
EXAONE API Platform에서 키를 발급받습니다.
2. 실행 방식 고르기
방식 | 명령 | 장점 | 단점 |
npx (권장) |
| 미리 설치할 필요가 없고 새 버전이 자동으로 반영됨 | 첫 실행 때 내려받느라 몇 초 걸림 |
전역 설치 |
| 시작이 빠르고, 한 번 설치하면 인터넷 없이도 실행됨 | 업데이트를 직접 해야 함 |
전역 설치는 이렇게 합니다. 업데이트할 때도 같은 명령을 다시 실행합니다.
npm install -g k-exaone-mcp@latest설치를 확인합니다. 버전 번호가 나오면 정상입니다.
k-exaone-mcp --version
npm install k-exaone-mcp처럼-g없이 설치하면 현재 폴더의node_modules에만 설치돼서 MCP 클라이언트가 찾지 못합니다. 반드시-g를 붙이세요.
아래 설정 예시는 npx 방식 기준입니다. 전역 설치를 했다면 npx -y k-exaone-mcp 부분을 k-exaone-mcp로 바꾸면 됩니다. JSON 설정에서는 "command": "k-exaone-mcp", "args": []가 되고, Windows에서는 "command": "cmd", "args": ["/c", "k-exaone-mcp"]가 됩니다.
3. MCP 클라이언트에 등록
필요한 설정은 EXAONE_API_KEY 하나뿐입니다. 공식 가이드에 나온 temperature=1.0, top_p=0.95, preserve_thinking=true 같은 권장값은 서버에 기본값으로 들어 있습니다. 추론 강도나 시간 제한 같은 값을 바꾸는 방법은 세부 설정 바꾸기를 보세요.
이 서버는 로컬에서 실행되는 stdio 방식 MCP 서버입니다. 로컬 MCP 서버를 실행할 수 있는 클라이언트라면 어디서든 쓸 수 있습니다.
클라이언트 | 지원 | 비고 |
Claude Code · Claude Desktop | ✅ | |
Google Antigravity (Gemini) | ✅ | |
OpenAI Codex (CLI · IDE 확장 · ChatGPT 데스크탑 앱의 Codex) | ✅ | 세 곳이 |
VS Code (Copilot) · Cline · Cursor · Cherry Studio 등 | ✅ | |
ChatGPT 채팅 (웹 · 모바일 · 데스크탑 채팅 화면) | ❌ | ChatGPT 채팅은 인터넷에 공개된 원격(HTTPS) MCP 서버만 연결할 수 있어서 로컬 stdio 서버를 띄우지 못합니다. ChatGPT 데스크탑 앱에서는 Codex 화면에서 쓰세요 |
macOS · Linux:
claude mcp add exaone --scope user -e EXAONE_API_KEY=발급받은키 -- npx -y k-exaone-mcpWindows에서는 npx 앞에 cmd /c를 붙입니다. 명령 프롬프트(cmd)나 Git Bash에서는 이렇게 실행합니다.
claude mcp add exaone --scope user -e EXAONE_API_KEY=발급받은키 -- cmd /c npx -y k-exaone-mcpWindows PowerShell에서는 --를 따옴표로 감싼 '--'로 써야 합니다. PowerShell이 그냥 쓴 --를 지워 버려서 error: unknown option '-y'가 납니다.
claude mcp add exaone --scope user -e EXAONE_API_KEY=발급받은키 '--' cmd /c npx -y k-exaone-mcp등록됐는지 확인합니다. 도구는 새로 연 세션부터 보입니다.
claude mcp list설정 → 개발자 → 구성 편집에서 claude_desktop_config.json을 엽니다.
{
"mcpServers": {
"exaone": {
"command": "npx",
"args": ["-y", "k-exaone-mcp"],
"env": { "EXAONE_API_KEY": "발급받은키" }
}
}
}에이전트 패널의 … 메뉴에서 MCP Servers → Manage MCP Servers → View raw config를 열고 mcpServers에 Claude Desktop과 같은 블록을 추가합니다.
명령으로 등록합니다.
codex mcp add exaone --env EXAONE_API_KEY=발급받은키 -- npx -y k-exaone-mcpWindows PowerShell에서는 Claude Code와 마찬가지로 --를 '--'로 씁니다.
등록한 뒤 ~/.codex/config.toml(Windows는 %USERPROFILE%\.codex\config.toml)을 열어 tool_timeout_sec을 추가합니다. Codex는 도구 하나가 60초 안에 끝나지 않으면 끊는데, EXAONE이 깊게 추론하면 60초를 넘길 수 있습니다.
처음부터 파일을 직접 써도 됩니다.
[mcp_servers.exaone]
command = "npx"
args = ["-y", "k-exaone-mcp"]
tool_timeout_sec = 600 # 도구 실행 시간 제한(초). 기본 60
startup_timeout_sec = 30 # 서버 시작 대기(초). npx 첫 실행은 내려받느라 느릴 수 있음
[mcp_servers.exaone.env]
EXAONE_API_KEY = "발급받은키"codex mcp list로 등록 여부를 확인합니다. CLI, IDE 확장, ChatGPT 데스크탑 앱의 Codex가 이 파일을 함께 쓰므로 한 번만 등록하면 됩니다. 이 파일에는 키가 평문으로 저장되므로 저장소에 올리지 마세요.
mcpServers 형식을 쓰는 클라이언트에는 Claude Desktop과 같은 JSON을 넣습니다. VS Code의 .vscode/mcp.json은 키 이름이 servers입니다.
{
"servers": {
"exaone": {
"command": "npx",
"args": ["-y", "k-exaone-mcp"],
"env": { "EXAONE_API_KEY": "발급받은키" }
}
}
}4. 사용 예시
클라이언트를 다시 시작하거나 새 세션을 연 뒤, 평소처럼 말로 지시하면 됩니다. 호출한 AI가 도구 설명을 보고 ask_exaone을 알아서 호출합니다. **"엑사원"이나 "EXAONE"**이라고 이름을 말하면 가장 확실하게 알아듣습니다.
하고 싶은 것 | 이렇게 요청 |
연결 확인 | "exaone_status로 연결 확인해 줘" |
질문·작업 위임 | "엑사원한테 이 함수 이름 후보 5개 받아 줘" |
파일 리뷰 | " |
문서 다듬기 | "이 README 초안을 엑사원한테 자연스러운 한국어로 다듬어 달라고 해" |
교차 검증 | "네 답이랑 엑사원 답을 비교해서 차이점 정리해 줘" |
이어서 질문 | "방금 엑사원 답변에 이어서, 2번 항목을 더 자세히 물어봐 줘" |
추론 강도 지정 | "엑사원한테 |
처음 호출하면 클라이언트가 도구 사용 허락을 묻습니다. 매번 묻지 않게 하려면 "항상 허용"을 고르세요.
답변 끝의
[k-exaone-mcp]꼬리말에서 토큰 사용량과 남은 호출 수를 확인할 수 있습니다.정해진 상황에 자동으로 맡기려면 프로젝트의
CLAUDE.md(Codex는AGENTS.md)에 규칙을 적어 둡니다. 예: "한국어 문서를 다듬을 때는 ask_exaone으로 엑사원 의견도 받는다"
도구
ask_exaone
인자 | 타입 | 설명 |
| string, 필수 | EXAONE에게 보낼 지시나 질문. EXAONE은 대화 맥락을 모르므로 필요한 내용을 모두 담아야 합니다. |
| string | 시스템 프롬프트. 새 대화를 시작할 때만 적용됩니다. |
| string[] | 첨부할 UTF-8 텍스트 파일 경로(절대 경로 권장). 바이너리는 거부합니다. |
| string | 이전 대화를 이어 갈 때 씁니다. |
|
| 추론 강도. 기본값은 |
| int | 생성 토큰 상한(추론 포함). 보통은 비워 둡니다. |
| boolean | EXAONE의 추론 과정도 함께 돌려받습니다. 기본값은 false입니다. |
응답 예시:
이 프로젝트는 MCP 클라이언트가 K-EXAONE 2.5에게 작업을 위임하게 해 주는 MCP 서버입니다.
---
[k-exaone-mcp]
conversation_id: eaa07c68-702d-4731-b274-c657950c09cd (turn 1)
model: k-exaone_v2.5 · effort: low · 2.5s
tokens: in 555 / out 61 (reasoning 13)
rate limit remaining: second 0/1, minute 59/60, day 89/100
attached: C:\work\project\package.jsonexaone_status
설정(키는 끝 4자리만 표시), 이 서버 프로세스의 누적 토큰 사용량, 마지막으로 받은 호출 한도 헤더를 보여 줍니다. ping: true(기본값)이면 작은 요청을 한 번 보내 키와 연결 상태를 확인합니다.
사용량과 호출 한도
EXAONE API는 응답 헤더로 남은 호출 횟수를 알려 줍니다. 토큰 사용량은 응답 본문의 usage에 들어 있습니다. 둘 다 이 서버가 읽어서 보여 줍니다.
헤더 | 의미 |
| 구간별 최대 호출 횟수 |
| 구간별 남은 호출 횟수 |
| 다시 요청할 수 있을 때까지 기다릴 시간 |
2026-11-10에 무료 키로 실제 호출했을 때 관측한 한도는 초당 1회, 분당 60회, 하루 100회였습니다. 한도는 계정이나 정책에 따라 달라질 수 있습니다. 하루 100회는 에이전트가 쓰기에는 빠듯하므로, 꼭 필요한 작업만 맡기는 위임·검토 용도에 맞습니다.
계정 전체의 누적 사용량을 조회하는 API는 없습니다(GET /v1/usage는 404). 계정 전체 사용량은 EXAONE API Platform 콘솔에서 확인하세요.
세부 설정 바꾸기
모든 설정은 환경변수로 바꿉니다. 키 외에는 모두 선택 사항이고, 넣지 않으면 기본값을 씁니다.
설정 항목
변수 | 기본값 | 허용 값 | 설명 |
| (필수) | API 키 | |
|
|
| 호출할 때 |
|
| 1000 이상 (ms) | EXAONE 응답을 기다리는 최대 시간. 예: |
| (없음) | 1 이상 | 기본 생성 토큰 상한(추론 포함). 비워 두면 API 서버 기본값을 씁니다. |
| 서버 실행 폴더 | 폴더 경로 |
|
|
| 1 이상 (KB) | 첨부 파일 하나의 최대 크기 |
|
| 1 이상 (KB) | 한 번에 첨부하는 파일 합계의 최대 크기. 1800 이하를 권장합니다(첨부 파일 크기 한도 참고). |
|
| 0 이상 | 샘플링 무작위성(공식 권장값 1.0) |
|
| 0 ~ 1 | 누적 확률 상한(공식 권장값 0.95) |
|
|
| 대화를 이어 갈 때 이전 추론을 함께 보낼지 여부. |
|
| URL | OpenAI 호환으로 띄운 다른 EXAONE 엔드포인트(vLLM 등)에 연결할 때 바꿉니다. |
|
| 모델 ID |
값이 잘못되면(예: EXAONE_REASONING_EFFORT=ultra) 서버가 시작하지 않고, 클라이언트 로그에 어떤 값이 잘못됐는지 표시됩니다.
클라이언트별 변경 방법
설정을 바꾼 뒤에는 클라이언트를 다시 시작해야 적용됩니다. Claude Code와 Codex는 새 세션을 열면 됩니다.
JSON 설정을 쓰는 클라이언트 (Claude Desktop, Antigravity, VS Code, Cline, Cursor 등): env에 항목을 추가합니다.
{
"mcpServers": {
"exaone": {
"command": "npx",
"args": ["-y", "k-exaone-mcp"],
"env": {
"EXAONE_API_KEY": "발급받은키",
"EXAONE_REASONING_EFFORT": "medium",
"EXAONE_TIMEOUT_MS": "300000"
}
}
}
}Claude Code: 등록할 때 -e를 여러 번 붙입니다. 이미 등록한 서버의 설정을 바꾸려면 지우고 다시 등록합니다.
claude mcp remove exaone --scope user
claude mcp add exaone --scope user -e EXAONE_API_KEY=발급받은키 -e EXAONE_REASONING_EFFORT=medium -e EXAONE_TIMEOUT_MS=300000 -- npx -y k-exaone-mcpWindows에서는 npx 앞에 cmd /c를 붙이고, PowerShell이면 --를 '--'로 씁니다(Claude Code 등록 참고).
~/.claude.json에서 mcpServers.exaone.env를 직접 고쳐도 됩니다.
Codex: ~/.codex/config.toml의 env 표에 줄을 추가합니다.
[mcp_servers.exaone.env]
EXAONE_API_KEY = "발급받은키"
EXAONE_REASONING_EFFORT = "medium"
EXAONE_TIMEOUT_MS = "300000"시간 제한은 두 군데에 있습니다
EXAONE 응답을 기다리는 시간은 서버 제한과 클라이언트 제한 중 짧은 쪽으로 결정됩니다. 긴 작업을 맡기려면 둘 다 늘려야 합니다.
위치 | 설정 | 기본값 |
이 서버 |
| 10분 |
Codex |
| 60초 |
Claude Code | 환경변수 | 클라이언트 기본값 |
그 밖의 클라이언트 | 각 클라이언트 문서 참고 |
자주 쓰는 조합
목적 | 설정 |
빠른 응답 위주 (간단한 질문, 번역) |
|
코드 리뷰·설계 검토 | 기본값 그대로 ( |
어려운 문제를 오래 생각하게 |
|
첨부를 최대한 크게 |
|
설정이 제대로 들어갔는지는 exaone_status 도구로 확인할 수 있습니다. 결과의 ## 설정 항목에 지금 적용된 값이 나옵니다.
첨부 파일 크기 한도
EXAONE API의 한도는 바이트가 아니라 토큰입니다. 공식 가이드에 따르면 입력 토큰 수와 max_tokens의 합이 524,288 토큰을 넘으면 400 오류가 납니다. 파일 크기(MB)나 요청 본문 크기에 대한 별도 한도는 문서에 없습니다.
2026-11-10에 실제 API의 usage.prompt_tokens로 재 보니 약 3.9바이트가 1토큰이었습니다.
샘플 | 바이트 | 토큰 | 바이트/토큰 |
한국어 문서(이 README) | 18,407 | 4,682 | 3.93 |
TypeScript 코드(한글 메시지 포함) | 27,114 | 6,979 | 3.89 |
이 비율로 환산하면 컨텍스트 전체는 약 2.0MB입니다. 여기서 추론과 답변에 쓸 출력 몫, system 프롬프트, 질문을 빼야 하므로 첨부 합계는 약 1.8MB가 현실적인 최대입니다. 내용이나 언어에 따라 비율은 달라질 수 있습니다.
기본값을 이렇게 정한 이유는 다음과 같습니다.
EXAONE_MAX_TOTAL_KB=1536(1.5MB): 약 40만 토큰으로 컨텍스트의 약 77%입니다. 높은 추론 강도에서도 출력에 쓸 토큰을 넉넉히 남깁니다.EXAONE_MAX_FILE_KB=1536: 합계 한도와 같게 두어, 큰 파일 하나를 통째로 보낼 수 있게 했습니다.서버는 상한을 강제하지 않습니다. 더 크게 설정할 수는 있지만, 토큰 한도를 넘으면 API가 400 오류를 돌려줍니다.
대화를 이어 가면 첨부가 다시 전송됩니다. conversation_id로 대화를 이어 가면 이전 턴에 첨부한 파일도 대화 기록에 남아 매번 함께 전송됩니다. 1.5MB를 첨부한 대화는 다음 턴에서 바로 한도를 넘을 수 있으므로, 큰 첨부는 새 대화로 한 번만 보내세요.
알아 둘 점
EXAONE은 직접 파일을 수정하거나 명령을 실행하지 않습니다. 결과를 받아 실제로 반영하는 것은 호출한 AI(Claude 등)입니다.
K-EXAONE 2.5는 텍스트 전용 모델입니다. 이미지와 PDF는 첨부할 수 없습니다.
대화 기록은 서버 메모리에만 있습니다. 클라이언트를 다시 시작하면 사라집니다(최근 50개 대화, 대화당 20턴까지 보관).
첨부한 파일 내용과 질문은 EXAONE API로 전송됩니다. 회사 코드를 보내기 전에 이용약관을 확인하세요.
API 키는 로그나 도구 출력에 끝 4자리만 나옵니다.
개발
npm install
npm run typecheck && npm test # 단위·통합 테스트 (API 호출 없음)
npm run build # dist/ 생성실제 API로 확인하려면 .env.example을 .env로 복사하고 키를 넣은 뒤 실행합니다. 두 명령 모두 일일 호출 한도를 소모합니다.
npm run verify:api # 헤더·usage·reasoning_effort·tool calling 등 11개 항목 확인 (약 11회 호출)
npm run smoke # 빌드된 서버를 stdio MCP로 띄워 실제 사용 흐름 확인 (2회 호출)
npm run inspect # MCP Inspector로 도구를 직접 호출해 보기npm 배포 전에 로컬 빌드로 연결하려면 npx -y k-exaone-mcp 대신 node /절대경로/k-exaone-mcp/dist/index.js를 씁니다.
구조
레이어드 아키텍처로 나눴고, 의존 방향은 위에서 아래로만 흐릅니다.
src/
├─ index.ts 진입점: 설정을 읽고 각 계층을 조립해 stdio 서버 실행
├─ config.ts 환경변수 → AppConfig
├─ presentation/ MCP 도구 정의, 입력 검증(zod), 응답 문구
├─ application/ 유스케이스(ask, status) 흐름 조율
├─ domain/ 모델, 대화, 첨부 규칙, 사용량 집계, 포트(인터페이스)
└─ infrastructure/ EXAONE HTTP·SSE 클라이언트, 파일 읽기, 메모리 저장소라이선스
Available Tools
2 toolsask_exaoneAsk K-EXAONEARead-only
Delegate a task or question to K-EXAONE 2.5 (LG AI Research) and return its answer.
Use it to get an independent second opinion, a Korean-native draft or review, or to offload a self-contained subtask.
EXAONE cannot see your workspace, tools or this conversation: put every needed fact in prompt, or pass local text files with files (the server reads them itself, so their contents do not have to pass through your context).
EXAONE is text-only and always reasons before answering. Higher reasoning_effort is slower and uses more tokens.
To ask a follow-up in the same thread, pass the conversation_id printed at the end of the previous answer.
The answer ends with a [k-exaone-mcp] footer showing token usage and remaining API rate limits.
Inputs: prompt (required), files, system, max_tokens, +3 more.
exaone_statusK-EXAONE status & usageARead-only
Show k-exaone-mcp settings, token usage accumulated by this server process, and the latest EXAONE API rate-limit headers. With ping=true (default) it also sends one tiny request to verify the API key and connectivity.
Inputs: ping.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools occupy completely separate roles: ask_exaone performs model delegation/inference, while exaone_status reports configuration, token usage, and API health. An agent cannot plausibly confuse a query tool with a diagnostics tool, and the descriptions reinforce the boundary.
Both names are snake_case and share the `exaone` token, giving a recognisable family. However, ask_exaone is verb-first while exaone_status is prefix-first, a minor structural deviation rather than a real inconsistency.
Two tools is thin in absolute terms, but the server's scope is deliberately narrow (single-model delegation plus health check), and both tools earn their place. Nothing is missing that would warrant an extra tool purely for count's sake.
The core lifecycle is covered: stateless asks, file-passing, multi-turn follow-ups via conversation_id, and a status/connectivity check. Gaps are minor — there is no way to list, inspect, or delete existing conversation threads, and no parameter/model discovery beyond status.
Maintenance
Related MCP Connectors
Official MCP bridge to Exogram—the Personal AI Agent for your work, people, and life.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Work management where AI agents are first-class members: tasks, projects, memory over hosted MCP
Task management your AI agents can actually run. One line becomes a context-ready task over MCP.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables MCP chat clients to read explicitly shared local source files and search results without spending local model quota, while also providing an experimental quota-relay workflow for extended modes.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables delegating tasks to agents you configure yourself through OpenAI-compatible Chat Completions backends, with automatic or explicit routing, synchronous calls, persistent asynchronous jobs, and multi-step reviewed workflows. It returns proposals and analyses only, leaving file changes, command execution, and approvals under the MCP client's control.28 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents such as ChatGPT, Claude, and local LLMs to operate an enterprise digital-operations platform through MCP, exposing 19 model tools and 3 app-only tools for identity, data, workflow, files, and PII-controlled operations with role-based permissions and two-phase confirmations.Apache 2.0
- AlicenseNot gradedqualityAmaintenanceEnables AI clients to manage workspaces, projects, tasks, and AI agents through natural language, with hosted or local connection options and OpenAPI-to-MCP tool generation.2,530 npmMIT