gemini
Gemini CLI MCP Server for Claude Code
Installation
npx @dongju101/gemini-mcpAsk AI about gemini
Powered by Claude ยท Grounded in docs
I know everything about gemini. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
gemini-mcp
Gemini CLI๋ฅผ Subprocess๋ก ํธ์ถํ๋ MCP Server. Gemini Pro ๊ตฌ๋ (Google AI Pro)์ OAuth ์ธ์ฆ์ ํ์ฉํ์ฌ API Key ์์ด Gemini๋ฅผ ์ฌ์ฉํ๋ค.
์ฌ์ ์กฐ๊ฑด
- Node.js 18+
- Gemini CLI ๊ธ๋ก๋ฒ ์ค์น ๋ฐ OAuth ์ธ์ฆ ์๋ฃ
npm install -g @google/gemini-cli
gemini # ์ต์ด ์คํ ์ OAuth ์ธ์ฆ ์งํ
npx๋ก ๋ฐ๋ก ์ฌ์ฉ
์ค์น ์์ด npx๋ก ์ฆ์ ์คํํ ์ ์๋ค.
Claude Code (ํ๋ก์ ํธ๋ณ .mcp.json ๊ถ์ฅ):
ํ๋ก์ ํธ ๋ฃจํธ์ .mcp.json ํ์ผ์ ์์ฑํ๋ค.
{
"mcpServers": {
"gemini": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@dongju101/gemini-mcp@latest"]
}
}
}
์ด ๋ฐฉ์์ ํด๋น ํ๋ก์ ํธ์์๋ง gemini MCP server๊ฐ ๊ธฐ๋๋์ด ๋ค๋ฅธ ์ธ์
์ ์ํฅ์ ์ฃผ์ง ์๋๋ค.
.mcp.json์ .gitignore์ ์ถ๊ฐํ๊ฑฐ๋ ํ๊ณผ ๊ณต์ ํ ์ ์๋ค.
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"gemini": {
"command": "npx",
"args": ["-y", "@dongju101/gemini-mcp@latest"]
}
}
}
Workspace ๊ฒฝ๋ก override (์ ํ):
GEMINI_MCP_HOME=/custom/path npx @dongju101/gemini-mcp@latest
๋ฒ์ ๊ณ ์ ์ด ํ์ํ ๊ฒฝ์ฐ:
@latest๋์@0.2.3์ฒ๋ผ ํน์ ๋ฒ์ ์ ๋ช ์ํ ์ ์๋ค.
๋ฒ์ ์ ๋ฐ์ดํธ
npx๋ ์ ์ญ ์ค์น๋ ํจํค์ง๋ฅผ ์ฐ์ ์ฌ์ฉํ๋ฏ๋ก, ๊ตฌ๋ฒ์ ์ด ์ ์ญ์ ์ค์น๋์ด ์์ผ๋ฉด ์ ๋ฒ์ ์ด ๋ฐ์๋์ง ์๋๋ค.
# ์ ์ญ ์ค์น ์
๋ฐ์ดํธ
npm install -g @dongju101/gemini-mcp@latest
# npx ์บ์ ์ญ์ (์ ์ญ ์ค์น ์์ด npx ์บ์๋ง ์ฌ์ฉํ๋ ๊ฒฝ์ฐ)
rm -rf ~/.npm/_npx
์ ๋ฐ์ดํธ ํ Claude Code์์ MCP ์๋ฒ๋ฅผ ์ฌ์์ํ๋ค.
๊ธฐ๋ณธ Workspace๋ ํ๋ก์ ํธ ๋ฃจํธ์ .gemini-mcp/์ ์๋ ์์ฑ๋๋ค.
.gitignore์ .gemini-mcp/๋ฅผ ์ถ๊ฐํ์ฌ ์ปค๋ฐ์์ ์ ์ธํ๋ค.
๊ธฐ์กด ~/.gemini-mcp/ ์ฌ์ฉ์ ๋ง์ด๊ทธ๋ ์ด์
:
์ด์ ๋ฒ์ ์ ์ฌ์ฉ ์ค์ด์๋ค๋ฉด, ~/.gemini-mcp/์ session ๋ฐ์ดํฐ๊ฐ ๋จ์ ์์ ์ ์๋ค.
ํ์ํ ๋ฐ์ดํฐ๋ฅผ ํ๋ก์ ํธ ๋ฃจํธ์ .gemini-mcp/๋ก ๋ณต์ฌํ๊ฑฐ๋ ์ญ์ ํ๋ค.
# ์ด์ ๋ฐ์ดํฐ ์ ๊ฑฐ (์ ํ)
rm -rf ~/.gemini-mcp/
์์ค์์ ์ค์น
git clone https://github.com/DvwN-Lee/gemini_mcp.git
cd gemini_mcp
npm install
npm run build
ํ๋ก์ ํธ ๋ฃจํธ์ .mcp.json์ ์์ฑํ๋ค.
{
"mcpServers": {
"gemini": {
"type": "stdio",
"command": "node",
"args": ["/path/to/gemini_mcp/dist/server.js"]
}
}
}
์ค์
.gemini-mcp/config.json์ผ๋ก Server ๋์์ ์ ์ดํ๋ค.
Config ํ์ผ์ด ์๊ฑฐ๋ ์๋ชป๋ ๊ฒฝ์ฐ ๊ฐ ํญ๋ชฉ์ ๊ธฐ๋ณธ๊ฐ์ด ์ ์ฉ๋๋ค.
{
"file_access": true,
"model": "gemini-3-pro-preview",
"system_prompt": "You are a concise technical assistant.",
"timeout": 300,
"total_timeout": 600
}
ํ์ผ ์ ๊ทผ (file_access)
Gemini๊ฐ ํ๋ก์ ํธ ํ์ผ์ ์ ๊ทผํ ์ ์๋์ง๋ฅผ ์ ์ดํ๋ค.
| ๊ฐ | ๋์ |
|---|---|
true (๊ธฐ๋ณธ๊ฐ) | Project Root์์ ์คํ. Gemini๊ฐ ํ๋ก์ ํธ ํ์ผ์ ์ฝ๊ณ ๋ถ์ ๊ฐ๋ฅ. |
false | ๊ฒฉ๋ฆฌ๋ Workspace์์ ์คํ. ํ๋ก์ ํธ ํ์ผ ์ ๊ทผ ๋ถ๊ฐ. |
Model ์ ํ (model)
Gemini CLI์์ ์ฌ์ฉํ Model์ ์ง์ ํ๋ค.
| ๊ฐ | ๋์ |
|---|---|
| ๋ฏธ์ง์ (๊ธฐ๋ณธ๊ฐ) | auto mode -- Gemini๊ฐ ์ต์ ๋ชจ๋ธ์ ์๋ ์ ํ |
"gemini-3.1-pro-preview" | ์ต์ ๋ชจ๋ธ. ๋ณต์กํ ์ถ๋ก , agentic workflow, 1M context |
"gemini-3-pro-preview" | ๋ณต์กํ ์ถ๋ก , ์ฝ๋ ๋ถ์, ์ํคํ ์ฒ ์ค๊ณ |
"gemini-3-flash-preview" | ๋จ์ ์ง์, ๋ฒ์ญ, ์์ฝ ๋ฑ ๋น ๋ฅธ ์๋ต์ด ์ฐ์ ์ธ ์์ |
"gemini-2.5-pro" / "gemini-2.5-flash" | 3 ๊ณ์ด ๋ชจ๋ธ์ด quota ์ด๊ณผ ๋๋ ์ค๋ฅ ์ ๋์ฒด |
Tool ํธ์ถ ์ model Parameter๋ฅผ ์ง์ ์ง์ ํ๋ฉด Config ์ค์ ๋ณด๋ค ์ฐ์ ์ ์ฉ๋๋ค.
Timeout ์ค์ (timeout / total_timeout)
Gemini CLI ์๋ต ๋๊ธฐ ์๊ฐ์ ์ ์ดํ๋ค.
| ๊ฐ | ๋์ |
|---|---|
timeout | ์ค ๋จ์ ์๋ต ๋๊ธฐ ์๊ฐ(์ด). ์ด ์๊ฐ ๋์ ์ถ๋ ฅ์ด ์์ผ๋ฉด ํ์์์. ๊ธฐ๋ณธ๊ฐ: 300 |
total_timeout | ์ ์ฒด ์์ฒญ ์ต๋ ํ์ฉ ์๊ฐ(์ด). ๊ธฐ๋ณธ๊ฐ: 600 |
๋ณต์กํ ์ฝ๋๋ฒ ์ด์ค ๋ถ์์ฒ๋ผ ๊ธด ์์ฒญ์ Gemini API์ ์ฒซ ์๋ต๊น์ง ์ ๋ถ์ด ๊ฑธ๋ฆด ์ ์๋ค. ํ์ ์ ๊ฐ์ ๋๋ฆฐ๋ค.
์์คํ ํ๋กฌํํธ (system_prompt)
Gemini์๊ฒ ์ ๋ฌํ ๊ธฐ๋ณธ ์์คํ ํ๋กฌํํธ๋ฅผ ์ง์ ํ๋ค.
| ๊ฐ | ๋์ |
|---|---|
| ๋ฏธ์ง์ (๊ธฐ๋ณธ๊ฐ) | ๋ด์ฅ ๊ธฐ๋ณธ ํ๋กฌํํธ ์ฌ์ฉ (๊ฐ๊ฒฐํ ๊ธฐ์ ์ด์์คํดํธ ํ๋ฅด์๋) |
"<๋ฌธ์์ด>" | ์ง์ ํ ๋ฌธ์์ด์ ์์คํ ํ๋กฌํํธ๋ก ์ฌ์ฉ |
Session ๋๋ ํ ๋ฆฌ์ GEMINI.md์ ๊ธฐ๋ก๋์ด Gemini CLI์ ์ ๋ฌ๋๋ค. file_access: true์ด๋ฉด ํ๋ก์ ํธ ๋ฃจํธ ๊ฒฝ๋ก ๋ฐ ํ์ผ ์ฝ๊ธฐ ์ง์๋ ์๋์ผ๋ก ์ถ๊ฐ๋๋ค.
์ค์ ์์
# ๊ธฐ๋ณธ ๋ชจ๋ธ + ํ์ผ ์ ๊ทผ ํ์ฑํ
echo '{"file_access": true}' > .gemini-mcp/config.json
# ํน์ Model ๊ณ ์ + ํ์ผ ์ ๊ทผ ํ์ฑํ
echo '{"file_access": true, "model": "gemini-3-flash-preview"}' > .gemini-mcp/config.json
Tool ๋ชฉ๋ก
| Tool | Parameter | ์ฉ๋ |
|---|---|---|
gemini_chat | message, model, session, sandbox, change_mode, include_meta | Gemini์ ๋ํํ ์ง์. --resume์ผ๋ก ์ด์ ๋ํ ๋งฅ๋ฝ ์๋ ์ ์ง. |
gemini_reset | session | ๋ํ Session ์ด๊ธฐํ. ๋ค์ ํธ์ถ๋ถํฐ ์ ๋ํ ์์. |
gemini_fetch_chunk | cache_key, chunk_index | change_mode ์๋ต์ด ์ฌ๋ฌ chunk๋ก ๋ถํ ๋ ๊ฒฝ์ฐ ํ์ chunk ์กฐํ. |
gemini_chat Parameter
| Parameter | ๊ธฐ๋ณธ๊ฐ | ์ค๋ช |
|---|---|---|
message | (ํ์) | Gemini์ ์ ๋ฌํ ๋ฉ์์ง |
model | "" (auto) | ์ฌ์ฉํ ๋ชจ๋ธ. ๋น ๋ฌธ์์ด์ด๋ฉด Gemini๊ฐ ์ต์ ๋ชจ๋ธ์ ์๋ ์ ํ |
session | "default" | Session ์ด๋ฆ. ๋ ๋ฆฝ์ ์ธ ๋ํ ๋งฅ๋ฝ ์ ์ง |
sandbox | false | Sandbox mode๋ก code๋ฅผ ๊ฒฉ๋ฆฌ ํ๊ฒฝ์์ ์คํ |
change_mode | false | ์ฝ๋ ์์ ์์ฒญ ์ ํ์ฑํ. ์๋ต์ ๊ตฌ์กฐํ๋ OLD/NEW ํฌ๋งท์ผ๋ก ํ์ฑํ์ฌ Edit tool ์ ์ฉ ๊ฐ๋ฅ. |
include_meta | false | true ์ ์๋ต footer์ ์ฌ์ฉ model๋ช
๊ณผ token ์๋ฅผ ํ์. change_mode์ ํจ๊ป ์ฌ์ฉ ์ ์๋ ์ ์ฝ์ฌํญ ์ฐธ๊ณ . |
include_meta+change_mode๊ฒฐํฉ ์ ๋์:change_mode: true์include_meta: true๋ฅผ ๋์์ ์ฌ์ฉํ๋ ๊ฒฝ์ฐ, ํ์ฑ ์ฑ๊ณต/์คํจ์ ๊ด๊ณ์์ด meta footer(model๋ช , token ์)๊ฐ ์๋ต ๋์ ํฌํจ๋๋ค. ํ์ฑ ์ฑ๊ณต ์ ๊ตฌ์กฐํ๋ ํธ์ง ๊ฒฐ๊ณผ ๋ค์, ํ์ฑ ์คํจ ์ ์๋ณธ ์๋ต ๋ค์ footer๊ฐ ์ถ๊ฐ๋๋ค.
Multi-Session
์ฌ๋ฌ Terminal์์ ๋
๋ฆฝ์ ์ธ ๋ํ๋ฅผ ์ ์งํ ์ ์๋ค.
session Parameter๋ก Session ์ด๋ฆ์ ์ง์ ํ๋ฉด ๊ฐ๊ฐ์ ๋ํ ๋งฅ๋ฝ์ด ๊ฒฉ๋ฆฌ๋๋ค.
Terminal A (frontend ์์
):
gemini_chat(message="React Component ๊ตฌ์กฐ ์ค๋ช
ํด์ค", session="frontend")
gemini_chat(message="์ ๊ตฌ์กฐ์์ ์ํ ๊ด๋ฆฌ๋?", session="frontend") -> ์ด์ ๋งฅ๋ฝ ์ ์ง
Terminal B (backend ์์
):
gemini_chat(message="Express Router ํจํด ์๋ ค์ค", session="backend")
gemini_chat(message="์ ํจํด์ ์ธ์ฆ ์ถ๊ฐํ๋ ค๋ฉด?", session="backend") -> ๋
๋ฆฝ์ ๋งฅ๋ฝ ์ ์ง
session๋ฏธ์ง์ ์"default"Session ์ฌ์ฉ- Session๋ณ Workspace๊ฐ
.gemini-mcp/sessions/{session_name}/์ ์๋ ์์ฑ - Claude Code๋ฅผ ์ข
๋ฃํ๋ค ์ฌ์์ํด๋
--resume์ผ๋ก ์ง์ ๋ํ๋ฅผ ์ด์ด๊ฐ ์ ์๋ค gemini_reset(session="frontend"): ํน์ Session๋ง ์ด๊ธฐํgemini_reset(): ์ ์ฒด Session ์ด๊ธฐํ
๋๋ ํ ๋ฆฌ ๊ตฌ์กฐ
gemini_mcp/ # ์์ค Repository
src/
server.ts # FastMCP Server ์ง์
์ ยท Tool/Prompt/Resource ์ ์
runner.ts # Gemini CLI Subprocess ์คํ๊ธฐ
workspace.ts # Workspace ํ์ผ์์คํ
๊ด๋ฆฌ
changeMode.ts # change_mode ์๋ต ํ์ ๋ฐ chunk ์บ์
progress.ts # ProgressTracker (MCP notifications/progress)
util.ts # ๊ณตํต ์ ํธ๋ฆฌํฐ
types.ts # Type ์ ์ (GeminiResponse, RunnerEvent ๋ฑ)
__tests__/ # Vitest ํ
์คํธ
dist/ # TypeScript ๋น๋ ์ถ๋ ฅ
docs/ # ๊ธฐ์ ๋ฌธ์
package.json
tsconfig.json
vitest.config.ts
.gemini-mcp/ # Runtime Workspace (ํ๋ก์ ํธ ๋ฃจํธ์ ์๋ ์์ฑ)
config.json # Server ์ค์ (file_access, model, system_prompt)
.gemini/
settings.json # CLI ์ค์ (mcpServers: {}, security.auth)
sessions/ # Session๋ณ ๋
๋ฆฝ Workspace
ํ ์คํธ
npm test # Vitest ์คํ
npm run test:watch # Watch mode
๊ธฐ์ ๋ฌธ์
- ์ ๋ต ๋ถ์ -- 5๊ฐ ์ ๊ทผ ์ ๋ต ๋น๊ต ๋ฐ ์ ์ ๊ทผ๊ฑฐ
- ๊ธฐ์ ์กฐ์ฌ -- CLI ๋์ ๋ถ์, stream-json ๊ตฌ์กฐ, Cold Start ๋ถ์
- Architecture -- ์์คํ ๊ตฌ์กฐ, ๋ฐ์ดํฐ ํ๋ฆ, ๊ตฌํ ์ค๊ณ
- ์ฑ๋ฅ ๋ถ์ -- Token ์๋น ๋ฐ Latency ์ต์ ํ ๋ถ์
- ์ ์ฑ ์ค์ ๋ถ์ -- Gemini ToS ๋ฐ ์ฌ์ฉ ์ ์ฑ ์ค์ ๋ถ์
- Gemini ์ถ๋ ฅ ๋ถ์ -- stream-json ์ถ๋ ฅ ํฌ๋งท ๋ถ์
- ์ธ์ ๋ฆฌ์ ๋ถ์ -- Session ์ด๊ธฐํ ๋์ ๋ถ์
