# DeepSeek Chat MCP

A local MCP server and command-line tool that automates the DeepSeek website through a signed-in browser. It uses the website session; it does not call the DeepSeek API.

## How it works

1. The MCP client, command line, or optional HTTP API submits a prompt to this project.
2. The browser controller uses Patchright, a Playwright-compatible browser automation library, to manage a persistent Chrome session.
3. Chrome submits the prompt through the DeepSeek website and waits for the complete answer.
4. The answer returns to the caller. If Telegram forwarding is enabled, the answer or an error report can also be sent to a configured chat or forum topic.

DeepThink is checked and enabled before each query. The signed-in browser profile stays on the host running this project. Prompts are sent to DeepSeek through its website, and answers or error reports are sent to Telegram only when forwarding is enabled.

This project automates the DeepSeek website through its browser interface; it does not call the DeepSeek API. Patchright provides the browser-control APIs. The MCP server, DeepSeek selectors, query flow, response handling, Telegram integration, and recovery logic are implemented in this project.

## Requirements

- A Debian or Ubuntu server with systemd and sudo access.
- A 64-bit x86 Linux host. The installer downloads Chrome for Linux.
- Git, if you plan to clone the repository on the server.
- A DeepSeek account.
- Optional: a Telegram bot for message delivery.

## Install and run

On a clean server, install Git, clone the repository, and run the installer as the regular account that should own the browser session:

```bash
sudo apt-get update
sudo apt-get install -y git
git clone https://github.com/luisbianconi/deepseek-chat-mcp.git
cd deepseek-chat-mcp
bash setup-server.sh
```

The installer installs Node.js 22 when a suitable version is unavailable, project dependencies, Chrome and its Linux dependencies, Xvfb, and x11vnc, then creates and starts the systemd services. It prompts you to create a VNC password. Connect through an SSH tunnel to sign in to DeepSeek; the launcher then keeps the browser session available for CLI, MCP, HTTP, and example-script queries.

See [Automated Debian/Ubuntu server setup](#automated-debianubuntu-server-setup) for configuration, login, and service commands. `--fresh` starts a new chat before submitting a prompt.

## Example uses

These are example prompts to adapt to a country, city, or topic you choose:

- “Find current supermarket promotions in [country]. Summarize the strongest discounts, dates, and source links.”
- “Give me today's weather forecast for [city], including rain probability and source.”
- “Summarize today's important news about [country] with short neutral summaries, publication dates, and source links.”

## Components

- `cli.mjs` provides commands for launching the browser, querying, reading the last response, checking status, and running the MCP or HTTP server.
- `browser-controller.mjs` manages the Chrome connection, submits prompts, waits for responses, and enables DeepThink.
- `mcp-server.mjs` exposes query and browser controls to MCP clients over stdio.
- `http-api.mjs` provides an optional local HTTP interface protected by a bearer token.
- `telegram.mjs` handles optional Telegram delivery and message splitting.
- `setup-server.sh` provisions a Debian/Ubuntu server and starts the browser launcher as a systemd service.
- `selectors.json` maps page controls and response elements used by browser automation. Use `node cli.mjs check` to inspect these selectors after DeepSeek changes its interface.
- `package.json` declares dependencies, supported Node.js versions, and npm commands.

## JSON configuration

The `.deepseek-mcp/config.example.json` file in this repository is an anonymized reference template. It is not a live configuration file. Run `node cli.mjs telegram-config` to create the optional private user configuration; the command prints the runtime file path. Copy the relevant example settings into that file, replace every placeholder, and keep the completed file out of the repository.

Example:

```json
{
  "fresh": false,
  "telegram": {
    "enabled": false,
    "botToken": "YOUR_BOT_TOKEN",
    "chatId": "YOUR_CHAT_ID",
    "tid": 42,
    "errtid": 99
  },
  "http": {
    "host": "127.0.0.1",
    "port": 8765
  }
}
```

All values above are examples. Replace them with your own settings:

- `fresh` starts each query in a new chat when set to `true`.
- `telegram.enabled` enables message forwarding by default.
- `telegram.botToken` and `telegram.chatId` hold the Telegram bot token and default destination. Keep them private.
- `telegram.tid` is the default forum topic ID; `telegram.errtid` is the topic used for error reports. Omit either field if you do not need a default.
- `http.host` and `http.port` configure the optional HTTP API.

The JSON must use double quotes and have no trailing commas. The CLI flags `--telegram`, `--chatid`, `--tid`, and `--errtid` can enable forwarding or override configured destinations for one run. `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` can provide credentials through the process environment instead of the JSON file.

`selectors.json` is a separate, checked-in project file. It contains website selectors, not personal configuration. Do not put credentials or machine-specific state in it.

## Telegram

Add the bot to the destination chat and grant it permission to send messages. For topic delivery, use a forum-enabled group and grant the bot access to the required topics.

Example query:

```bash
node cli.mjs query --telegram --chatid=YOUR_CHAT_ID --tid=42 "Summarize the latest project release."
```

- `--telegram` enables forwarding for the invocation.
- `--chatid` selects the destination chat.
- `--tid` selects a forum topic; use `--tid=0` for the General topic.
- `--errtid` selects the topic for detailed error reports.

Long answers are split into Telegram-sized plain-text messages.

## Example shell script

`CronTabs/example.sh` shows how to call the CLI from Bash. It submits one generic prompt and does not contain a destination, schedule, or personal details.

```bash
bash CronTabs/example.sh
```

To schedule your own script, use an absolute path and ensure the scheduled environment can find Node.js. Keep personal scripts and settings outside a public checkout.

## MCP server

Run the stdio MCP server with:

```bash
node cli.mjs server
```

Example MCP client configuration; replace the path with the location of your checkout:

```json
{
  "mcpServers": {
    "deepseek-chat-mcp": {
      "command": "node",
      "args": ["/path/to/deepseek-chat-mcp/cli.mjs", "server"]
    }
  }
}
```

The server exposes `query`, `read_last_response`, `status`, `new_chat`, and `stop` tools. Add `--telegram` after `server` to enable forwarding for MCP queries.

## HTTP API

Start the optional API:

```bash
node cli.mjs http
```

It listens on `127.0.0.1:8765` by default and requires a bearer token generated in private application state. Available endpoints are `GET /status`, `GET /last`, `POST /query`, `POST /new`, and `POST /stop`.

Example request:

```bash
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Summarize the latest project release","fresh":true}' \
  http://127.0.0.1:8765/query
```

Keep the API bound to localhost unless you secure network access and protect the bearer token.

## Automated Debian/Ubuntu server setup

For a Linux server with systemd, copy the repository to the server and run:

```bash
bash setup-server.sh
```

Run it as the regular account that should own the browser session; it will request `sudo` for system packages and services. If Node.js 22 or newer is unavailable, the installer configures the NodeSource 22.x apt repository and installs Node.js from it. It also installs project dependencies, Chrome and its runtime dependencies, Xvfb, and x11vnc. It then installs and enables three systemd units: `deepseek-xvfb.service`, `deepseek-mcp-launch.service`, and `deepseek-vnc.service`. It exits without overwriting if one of those units already exists or the selected virtual display or VNC port is occupied; use it for a fresh deployment.

To provide Telegram settings before setup, copy `.deepseek-mcp/config.example.json` to `.deepseek-mcp/config.json` in the checkout and replace the placeholders. That real `config.json` is git-ignored. The installer copies it into the account's private runtime state. If no `config.json` is present in the checkout or on the account, the installer copies the example template instead. Telegram forwarding requires replacing the placeholders with valid values.

The setup creates a VNC password interactively and binds VNC to localhost only. To connect from another computer, open an SSH tunnel and point the VNC client at the local end:

```bash
ssh -L 5900:127.0.0.1:5900 USER@SERVER
```

After signing in to DeepSeek, VNC can be stopped while queries continue:

```bash
sudo systemctl stop deepseek-vnc.service
```

The VNC unit is separate from the browser launcher. Keep `deepseek-xvfb.service` and `deepseek-mcp-launch.service` active for queries. After signing in, try a query with `node cli.mjs query --fresh "Explain MCP in one sentence."`. The server setup script targets Debian/Ubuntu with systemd; it does not install or enable an unrelated VNC service on other distributions.

## Acknowledgments and contributions

Thanks to the maintainers and contributors of [Patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright-nodejs), [Playwright](https://playwright.dev/), the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk), Node.js, and the open-source projects this work depends on.

Suggestions, bug reports, documentation fixes, and code improvements are welcome. Open an issue or pull request with the behavior you observed and steps to reproduce it. Please remove account details, tokens, chat IDs, browser profiles, and other private data from logs or screenshots before sharing them.

## Limitations and next steps

- DeepSeek's website interface can change, which may require updates to `selectors.json` or the query flow.
- DeepThink is enabled for every query; this version does not expose a mode switch.
- The automated installer supports Debian/Ubuntu with systemd and a 64-bit x86 host.
- The server installer currently uses npm without a checked-in lockfile. A lockfile and clean-server CI run are planned to make installs more reproducible.
- The next deployment step is a container. Its browser profile and user configuration must live in persistent storage, with credentials kept out of the image.

## Privacy

Do not commit browser profiles, bearer tokens, Telegram credentials, or private user configuration. `.gitignore` excludes local state and ignores shell scripts other than `CronTabs/example.sh` and `setup-server.sh`.

## Creator

Luis Bianconi

## License

MIT. See [LICENSE](LICENSE).