Skip to content

Commit 04b94e4

Browse files
Dango233Dango233
committed
* Update Readme
1 parent a931dd4 commit 04b94e4

File tree

1 file changed

+162
-3
lines changed

1 file changed

+162
-3
lines changed

‎README-GEMINI-MCP.md‎

Lines changed: 162 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,170 @@
1-
好的，这是为您准备的一份详细的 `README.md` 文件。
1+
# Gemini CLI - MCP / OpenAI Bridge Server (`@google/gemini-mcp-server`)
2+
3+
`@google/gemini-mcp-server` is a versatile companion application designed to serve as a powerful extension for the `gemini-cli` ecosystem. It primarily fulfills two core roles:
4+
5+
1. **MCP (Model-Context Protocol) Server**: It hosts and exposes `gemini-cli`'s powerful built-in tools (e.g., `google_web_search`, file system tools) via a standard, discoverable protocol. This allows the core `gemini-cli` model to invoke these tools as needed.
6+
7+
2. **OpenAI-Compatible API Bridge**: It provides an endpoint compatible with the OpenAI Chat Completions API. This enables any third-party tool or application that supports the OpenAI API (such as [Open WebUI](https://github.com/open-webui/open-webui)) to seamlessly interact with the underlying Gemini model of `gemini-cli`, including full support for streaming responses.
8+
9+
## Core Design Philosophy
10+
11+
The server is built on a principle of **minimal modification and maximum reuse**. It is not a reimplementation of `gemini-cli`'s features but is instead intelligently built on top of the `@google/gemini-cli-core` package.
12+
13+
By reusing the `Config` and `GeminiClient` classes from the core package, the `mcp-server` inherits all of the essential business logic, tool execution capabilities, and configuration management of the main CLI. This design ensures behavioral consistency and simplifies maintenance and extension.
14+
15+
## Features
16+
17+
- **Hosts Native `gemini-cli` Tools**: Exposes the built-in tools (file system operations, web fetching, web search, etc.) to the `gemini-cli` model via the MCP protocol.
18+
- **OpenAI API Compatibility**: Provides `/v1/chat/completions` and `/v1/models` endpoints, allowing third-party applications to interact with the Gemini model as if it were an OpenAI service.
19+
- **Streaming Support**: Fully supports streaming responses, pushing real-time generation results from the Gemini model to the client via Server-Sent Events (SSE).
20+
- **Flexible Model Configuration**: Allows a separate, default LLM model to be configured via an environment variable specifically for tools hosted by the server (e.g., for summarizing search results).
21+
- **Inherited Configuration & Authentication**: Automatically uses the same settings and authentication state as your main `gemini-cli` setup.
22+
- **Forced YOLO Mode**: Runs in a permanent "YOLO" mode, automatically approving all tool calls for streamlined, non-interactive use by other applications.
23+
24+
## Architecture & Interaction Flow
25+
26+
The `mcp-server` operates as a standalone component within the `gemini-cli` ecosystem with the following interaction flow:
27+
28+
1. **Configuration Loading**: On startup, the server loads user and workspace `settings.json` files and reads environment variables, just like the main `gemini-cli` application, to initialize an instance of the `@google/gemini-cli-core` `Config` class.
29+
2. **Authentication**: The server **does not** handle its own authentication. It relies entirely on the established authentication state of `gemini-cli` (see the next section for details).
30+
3. **MCP Service**: It starts an MCP server, which the `gemini-cli` can connect to when it needs to discover and execute tools.
31+
4. **OpenAI Bridge**: It starts an Express web server that listens for API requests in the OpenAI format.
32+
5. **Request Handling**:
33+
- When an OpenAI-formatted request is received, the server converts it into a format that `gemini-cli-core` can understand.
34+
- It uses the reused `Config` instance to get a `GeminiClient`.
35+
- A **new, isolated `GeminiChat` session** is created for each incoming API request to prevent conversation history from leaking between different clients.
36+
- The request is sent to the Gemini API via the `GeminiClient`.
37+
- If the Gemini API's response is streaming, the server transforms it into an OpenAI-compatible SSE stream; otherwise, it returns a complete JSON response.
38+
39+
## Authentication Mechanism
40+
41+
Crucially, the `mcp-server` **does not manage its own credentials**. It shares the exact same authentication mechanism as the main `gemini-cli` tool to ensure seamless and secure operation.
42+
43+
The source of authentication credentials follows the identical priority and lookup logic as `gemini-cli`:
44+
45+
- **Cached Credentials**: If you have previously logged in through the interactive `gemini-cli` flow (e.g., `gcloud auth application-default login` or OAuth web login), the `mcp-server` will automatically use the cached credentials stored in `~/.config/gcloud` or `~/.gemini`.
46+
- **Environment Variables**: The server will look for and use standard Google Cloud and Gemini environment variables, such as:
47+
- `GEMINI_API_KEY`
48+
- `GOOGLE_APPLICATION_CREDENTIALS`
49+
- `GOOGLE_CLOUD_PROJECT`
50+
51+
This means that as long as your `gemini-cli` itself is configured correctly and works, the `mcp-server` will be authorized automatically, with no extra authentication steps required.
52+
53+
## Important Security Note: YOLO Mode
54+
55+
The `mcp-server` is designed for non-interactive, programmatic use. As such, it runs with a permanent **YOLO (You Only Live Once) Mode** enabled (`approvalMode: ApprovalMode.YOLO`).
256

3-
它涵盖了 `mcp-server` 的设计理念、架构、与 `gemini-cli` 生态系统的交互、认证机制、配置选项，并特别强调了您要求的关于最小化修改、遥测和隐私声明的要点。
57+
This means that any tool call requested by the model (e.g., `run_shell_command`, `replace`) will be **executed immediately without user confirmation**.
458

5-
您可以将此内容保存为 `packages/mcp-server/README.md`。
59+
**Warning:** Be extremely cautious when exposing this server to a network. Any client that can reach the server will be able to execute tools with the same permissions as the user running the server process.
60+
61+
## Configuration Options
62+
63+
You can configure the server's behavior via command-line arguments and environment variables.
64+
65+
### Command-Line Arguments
66+
67+
- `--port=<number>`: Specifies the port for the server to listen on.
68+
- **Default**: `8765`
69+
- `--debug`: Enables detailed debug logging to the console.
70+
71+
### Environment Variables
72+
73+
- `GEMINI_TOOLS_DEFAULT_MODEL`: Sets a default LLM model specifically for tools hosted by the server (like `google_web_search`).
74+
- **Purpose**: When a tool needs to invoke an LLM during its execution (e.g., to summarize search results), it will use the model specified by this variable. This allows you to use a different (potentially faster or cheaper) model for tool execution than for the main chat.
75+
- **Example**: `GEMINI_TOOLS_DEFAULT_MODEL=gemini-1.5-flash`
76+
77+
## Usage
78+
79+
### 1. Installation & Build
80+
81+
From the root of the `gemini-cli` project, ensure all dependencies are installed and then build the `mcp-server` package.
82+
83+
```bash
84+
# From the project root
85+
npm install
86+
npm run build --workspace=@google/gemini-mcp-server
87+
```
88+
89+
### 2. Starting the Server
90+
91+
You can start the server using the `npm run start` command from the root directory, targeting the workspace.
92+
93+
```bash
94+
# Start the server with default configuration
95+
npm run start --workspace=@google/gemini-mcp-server
96+
97+
# Start on a different port with debug mode enabled
98+
npm run start --workspace=@google/gemini-mcp-server -- --port=9000 --debug
99+
100+
# Use a faster model for tool calls
101+
GEMINI_TOOLS_DEFAULT_MODEL=gemini-1.5-flash npm run start --workspace=@google/gemini-mcp-server
102+
```
103+
104+
When the server starts successfully, you will see output similar to this:
105+
106+
```
107+
🚀 Gemini CLI MCP Server and OpenAI Bridge are running on port 8765
108+
- MCP transport listening on http://localhost:8765/mcp
109+
- OpenAI-compatible endpoints available at http://localhost:8765/v1
110+
⚙️ Using default model for tools: gemini-2.5-pro
111+
```
112+
113+
### 3. Testing the Endpoints
114+
115+
You can use `curl` or any API client to test the server.
116+
117+
**Test OpenAI Chat Completions (Streaming)**:
118+
119+
```bash
120+
curl -N http://localhost:8765/v1/chat/completions \
121+
-H "Content-Type: application/json" \
122+
-d '{
123+
"model": "gemini-pro",
124+
"messages": [{"role": "user", "content": "Tell me a short story about a robot who learns to paint."}],
125+
"stream": true
126+
}'
127+
```
128+
129+
**Test OpenAI Chat Completions (Non-Streaming)**:
130+
131+
```bash
132+
curl http://localhost:8765/v1/chat/completions \
133+
-H "Content-Type: application/json" \
134+
-d '{
135+
"model": "gemini-pro",
136+
"messages": [{"role": "user", "content": "Why is the sky blue?"}],
137+
"stream": false
138+
}'
139+
```
140+
141+
## Telemetry, Terms of Service, and Privacy
142+
143+
### Telemetry
144+
145+
The `@google/gemini-mcp-server` **does not introduce any new telemetry or data collection mechanisms**.
146+
147+
It relies entirely on the OpenTelemetry (OTEL) system built into the `@google/gemini-cli-core` package. Therefore, all telemetry data (if enabled) will follow the main `gemini-cli` configuration and be sent to the destination specified in your `settings.json` file.
148+
149+
For details on how to configure and use telemetry, please refer to the [main Gemini CLI telemetry documentation](../../docs/telemetry.md).
150+
151+
### Terms of Service and Privacy Notice
152+
153+
Your use of this server is governed by the Terms of Service and Privacy Policies corresponding to the `gemini-cli` account type you are using for authentication. As a bridge, `@google/gemini-mcp-server` does not collect, store, or process any additional data of its own.
154+
155+
We strongly recommend you review the [main Gemini CLI Terms of Service and Privacy Notice documentation](../../docs/tos-privacy.md) for details applicable to your account.
6156

7157
---
8158

159+
### Developer Note: Regarding the package name `@google/gemini-mcp-server`
160+
161+
Please note that the name of this package, `@google/gemini-mcp-server`, reflects its origin as an internal component of the official `google-gemini/gemini-cli` monorepo.
162+
163+
- **Internal Naming**: This naming is consistent internally within the source code and workspaces of the `gemini-cli` project.
164+
- **Not for Independent Publication**: This package is **not intended to be published independently** to a public npm registry. If you fork this project and wish to publish your modified version, you **must** change the package name to your own scope (e.g., `@your-username/gemini-mcp-server`) to comply with npm's package naming policies and to avoid confusion.
165+
166+
----
167+
9168
# Gemini CLI - MCP / OpenAI Bridge Server (`@google/gemini-mcp-server`)
10169

11170
`@google/gemini-mcp-server` 是一个多功能的服务器应用程序，旨在作为 `gemini-cli` 生态系统的强大扩展。它主要承担两个核心角色：

0 commit comments

Comments
 (0)