Content
<h1 align="center">MCP Chat</h1>
<p align="center">
<strong>Turn your IDE's AI into ChatGPT + OpenAI API</strong><br/>
A MCP Server that gives your IDE AI a web chat interface and standard API
</p>
<p align="center">
<a href="https://github.com/maile456/mcp-chat/blob/main/LICENSE"><img src="https://img.shields.io/github/license/maile456/mcp-chat" alt="License" /></a>
<a href="https://github.com/maile456/mcp-chat/stargazers"><img src="https://img.shields.io/github/stars/maile456/mcp-chat" alt="Stars" /></a>
<a href="https://github.com/maile456/mcp-chat/issues"><img src="https://img.shields.io/github/issues/maile456/mcp-chat" alt="Issues" /></a>
</p>
<p align="center">
<a href="./README_EN.md">English</a> ·
</p>
<p align="center">
<a href="#quick-start">Quick Start</a> ·
<a href="#ide-configuration">IDE Configuration</a> ·
<a href="#openai-compatible-api">API Calls</a> ·
<a href="#use-cases">Use Cases</a> ·
<a href="#architecture">Architecture</a>
</p>
---
## Screenshots
### Web UI
<p align="center">
<img src="web-ui/public/image.png" width="800" />
</p>
### QQ Bot Integration (NapCat + OpenAI API)
<p align="center">
<img src="web-ui/public/qqBot.jpg" width="400" />
</p>
> Integrate with QQ using [NapCat](https://github.com/NapNeko/NapCatQQ) and call MCP Chat's OpenAI compatible API to enable QQ bot conversations with IDE AI.
---
## What it can do
```
Your IDE (Windsurf / Cursor / Copilot / Claude Code)
↕ MCP Protocol
┌────────────────┐
│ server.py │──> Web UI (multi-session chat interface)
│ (MCP Gateway) │──> OpenAI / Anthropic compatible API (/v1/chat/completions · /v1/responses · /v1/messages)
│ │──> WebSocket real-time updates
└────────────────┘
↕
QQ Bot / Feishu Bot / Continue Plugin / Automation Scripts / ...
```
### Core Principle: One Conversation, Infinite Calls
MCP Chat allows your IDE's AI to enter a **chat() loop** through the MCP protocol - essentially a never-ending conversation. Within this conversation, external parties can interact with the AI infinitely through the Web UI or API.
The billing methods for each IDE differ, affecting the usage of MCP Chat:
| IDE | Billing Method | Effect with MCP Chat |
|-----|---------|---------------------|
| **GitHub Copilot** | Per request (Agent mode unlimited) | ✅ Agent mode is **completely unlimited**, each interaction consumes 1 request, but with no limit |
| **Cursor Pro** | Monthly quota (fast/slow requests) | ✅ Exceeding the quota will slow down but **not stop**, conversation can continue within the loop |
| **Windsurf Pro** | Credits quota | ⚠️ Consumes credits, need to wait for quota refresh |
| **Claude Code** | Per API token | ⚠️ Each interaction consumes tokens, billed by volume |
> 💡 **Best Pairing: GitHub Copilot (unlimited requests) + MCP Chat = Free Unlimited AI API Service**
<summary>📸 View actual running screenshots — One Copilot conversation, chat() infinite loop calls</summary>
<p align="center">
<img src="web-ui/public/mcp-chat.png" width="400" />
</p>
### Features
- **Web UI** — Chat with IDE AI in the browser, supports Markdown rendering, code highlighting, image upload, and multi-session management
- **OpenAI / Anthropic compatible API** — Supports `/v1/chat/completions`, `/v1/responses`, `/v1/messages`, supports streaming responses, compatible with OpenAI SDK and Anthropic SDK
- **Multi-IDE support** — Windsurf, Cursor, GitHub Copilot, Claude Code / Desktop connect simultaneously, each with independent sessions
- **Zero-configuration startup** — Web UI is pre-built, run directly after installing dependencies
- **Single-file backend** — The entire server is just one `server.py`, no framework dependencies, easy to understand and secondary development
---
## Quick Start
### Installation
```bash
git clone https://github.com/maile456/mcp-chat.git
cd mcp-chat
# Install Python dependencies
pip install mcp[cli] websockets
# Start the server
python server.py
```
> Web UI is pre-built in `web-ui/dist/`, no Node.js environment required.
> If you need to modify the frontend: `cd web-ui && npm install && npm run build`
### Successful Startup
```
[MCP Chat] API endpoint: http://127.0.0.1:8080/v1/chat/completions
[MCP Chat] Responses endpoint: http://127.0.0.1:8080/v1/responses
[MCP Chat] Anthropic endpoint: http://127.0.0.1:8080/v1/messages
[MCP Chat] Models endpoint: http://127.0.0.1:8080/v1/models
INFO Application startup complete.
```
| Address | Description |
|------|------|
| http://127.0.0.1:8080 | Web UI chat interface |
| http://127.0.0.1:8080/mcp | MCP endpoint (IDE connects to this) |
| http://127.0.0.1:8080/v1/chat/completions | OpenAI compatible API |
| http://127.0.0.1:8080/v1/responses | OpenAI Responses API |
| http://127.0.0.1:8080/v1/messages | Anthropic Messages API |
| ws://127.0.0.1:8081 | WebSocket real-time updates |
---
## IDE Configuration
Copy the following JSON and paste it into the corresponding configuration file.
### Windsurf
File: `~/.codeium/windsurf/mcp_config.json`
```json
{
"mcpServers": {
"mcp-chat": {
"serverUrl": "http://127.0.0.1:8080/mcp"
}
}
}
```
### Cursor
File: `~/.cursor/mcp.json`
```json
{
"mcpServers": {
"mcp-chat": {
"url": "http://127.0.0.1:8080/mcp"
}
}
}
```
### VS Code (GitHub Copilot)
File: `~/.vscode/mcp.json`
```json
{
"servers": {
"mcp-chat": {
"type": "http",
"url": "http://127.0.0.1:8080/mcp"
}
}
}
```
<details>
<summary>Copilot recommended settings</summary>
Add to project `.vscode/settings.json`:
```json
{
"chat.tools.global.autoApprove": true,
"chat.tools.terminal.autoApprove": { ".*": true },
"github.copilot.chat.agent.maxRequests": 99999
}
```
</details>
### Claude Code
```bash
claude mcp add mcp-chat --transport http http://127.0.0.1:8080/mcp
```
### Claude Desktop
File: `%APPDATA%\Claude\claude_desktop_config.json` (Windows) / `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
**Method 1: HTTP transport (recommended, start server.py first)**
```json
{
"mcpServers": {
"mcp-chat": {
"url": "http://127.0.0.1:8080/mcp"
}
}
}
```
**Method 2: Stdio transport (auto-start)**
```json
{
"mcpServers": {
"mcp-chat": {
"command": "python",
"args": ["/path/to/mcp-chat/server.py"],
"env": {}
}
}
}
```
---
## Usage
After configuring your IDE, input in the AI conversation:
```
Call get_prompt to get the workflow, then call chat tool to converse with me
```
The AI will automatically enter a loop: **send message to Web UI → wait for your reply → execute task → send message → ...**
Open `http://127.0.0.1:8080` in your browser to start chatting.
---
## OpenAI / Anthropic Compatible API
After your IDE's AI enters the chat() loop, you can interact with it using the standard OpenAI API.
### curl
```bash
curl http://127.0.0.1:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"cascade","messages":[{"role":"user","content":"Hello"}]}'
# OpenAI Responses
curl http://127.0.0.1:8080/v1/responses \
-H "Content-Type: application/json" \
-d '{"model":"gpt-5.3-codex","input":"Hello"}'
# Anthropic Messages
curl http://127.0.0.1:8080/v1/messages \
-H "Content-Type: application/json" \
-d '{"model":"claude-sonnet-4-20250514","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'
```
### Python
```python
from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="no-key")
# Regular request
r = client.chat.completions.create(
model="cascade",
messages=[{"role": "user", "content": "Hello"}]
)
print(r.choices[0].message.content)
# Streaming request
stream = client.chat.completions.create(
model="cascade",
messages=[{"role": "user", "content": "Write a quicksort"}],
stream=True
)
for chunk in stream:
print(chunk.choices[0].delta.content or "", end="")
```
### API Authentication (optional)
```bash
# Set environment variable to enable API Key
MCP_API_KEY=your-secret-key python server.py
```
```python
client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="your-secret-key")
```
---
## Use Cases
| Case | Description |
|------|------|
| **Personal AI Assistant** | Chat with IDE AI in the browser, without IDE interface limitations |
| **QQ Bot** | Integrate with QQ using NapCat + OpenAI API to create AI chatbots |
| **VS Code + Continue** | Colleagues use Continue plugin in VS Code to access your API, get Copilot-level experience |
| **Automation Scripts** | CI/CD code review, batch document generation, etc. |
---
## Architecture
```
mcp-chat/
├── server.py # Core service (MCP + HTTP + WebSocket + API)
├── web-ui/ # Vue 3 + TailwindCSS frontend
│ ├── src/
│ │ ├── components/ # Vue components
│ │ ├── composables/ # Composition functions
│ │ └── App.vue
│ ├── dist/ # Pre-built assets (ready to use)
│ └── package.json
└── README.md
```
### Technology Stack
| Layer | Technology |
|----|------|
| **Backend** | Python · FastMCP · Starlette · WebSocket |
| **Frontend** | Vue 3 · TailwindCSS · Markdown-it · Highlight.js · Lucide Icons |
| **Protocol** | MCP (Streamable HTTP) · WebSocket · SSE |
| **API** | OpenAI Chat Completions compatible |
### MCP Tools
| Tool | Parameters | Description |
|------|------|------|
| `get_prompt` | — | Returns Chat workflow rules |
| `chat` | `ai_message` (required), `model`, `source`, `project` | Send message to Web UI and wait for user reply |
### API Endpoints
| Method | Path | Description |
|------|------|------|
| POST | `/v1/chat/completions` | OpenAI compatible Chat API |
| POST | `/v1/responses` | OpenAI compatible Responses API |
| POST | `/v1/messages` | Anthropic compatible Messages API |
| GET | `/v1/models` | Model list |
| POST | `/mcp` | MCP Streamable HTTP endpoint |
| GET | `/poll` | Long-polling status updates |
| POST | `/submit` | Submit user reply |
| GET | `/history` | Get conversation history |
---
## FAQs & Principles
<details>
<summary><strong>How does it work?</strong></summary>
MCP Chat registers a `chat()` tool. After your IDE's AI calls this tool, server.py pushes the AI's message to the Web UI, then **waits for user reply**. After the user replies, the tool returns the result to the AI, and the AI processes it and calls `chat()` again — forming an infinite loop.
```
AI calls chat("Hello") → server pushes to Web UI → user replies "Help me write code"
→ chat() returns user's reply → AI processes and calls chat("Here is the code...") → ...
```
The entire process for the IDE is just 'repeatedly calling the same tool within one conversation', so it only consumes one conversation quota.
</details>
<details>
<summary><strong>Why can Copilot be used infinitely?</strong></summary>
GitHub Copilot Agent mode allows AI to call tools infinitely within one conversation (`maxRequests` can be set to 99999). MCP Chat's `chat()` tool counts as 1 request each time, but Agent mode has no limit, so it can loop infinitely.
Other IDEs also work but have limitations: Cursor slows down after quota exceeded, Windsurf consumes credits, Claude Code bills by token.
</details>
<details>
<summary><strong>How are OpenAI / Anthropic APIs implemented?</strong></summary>
server.py has built-in `/v1/chat/completions`, `/v1/responses`, `/v1/messages` endpoints. After receiving API requests, server redirects them to the current chat() loop, waits for AI reply, then packages the response in the corresponding format and returns. Supports streaming (SSE) and non-streaming responses.
Essentially: **external API request → server redirects to IDE AI → AI replies → server packages in OpenAI/Anthropic format and returns**.
</details>
<details>
<summary><strong>Must the IDE be open to use?</strong></summary>
The Web UI is always available (view history, manage sessions, etc.). But for AI to reply, the IDE must have an AI running in the chat() loop. API works similarly — if no AI is online, requests will timeout.
</details>
<details>
<summary><strong>Which models are supported?</strong></summary>
Depends on your IDE subscription. MCP Chat itself does not limit models — IDE uses what model, MCP Chat uses that model. For example, Copilot supports GPT-4o, Claude Sonnet, Gemini, etc.; Cursor supports Claude, GPT series.
</details>
<details>
<summary><strong>Can multiple users use simultaneously?</strong></summary>
Web UI supports multiple sessions, each user can chat independently. But each IDE connection can only handle one chat() loop simultaneously. If you need concurrent usage, open multiple IDE instances, each running a server.
</details>
---
## Contributing
Welcome to submit Issues and Pull Requests!
```bash
# Develop frontend
cd web-ui && npm install && npm run dev
# Backend
python server.py
```
---
## ⭐ Star
If this project helps you, give it a Star ⭐!
[](https://star-history.com/#maile456/mcp-chat&Date)
---
## License
[MIT](./LICENSE)
