# DeepSeek Search & Fetch MCP

![DeepSeek Search & Fetch MCP](assets/logo.svg)

A lightweight stdio MCP server for DeepSeek's official Search and Fetch APIs. It uses only Python's standard library and works with Hermes, **OpenCode v2**, Codex, Claude Code, and any MCP client that supports stdio servers.

## Requirements

- Python 3.10 or newer
- A DeepSeek API key with Search & Fetch API access

## Install

### For an agent

Configure the MCP client to start the server and pass `DEEPSEEK_API_KEY` as an environment variable. Do not put the key in the project files or commit it.

The server can be run directly from a cloned repository:

```sh
git clone https://github.com/Realmagnum/deepseek-search-mcp.git
cd deepseek-search-mcp
DEEPSEEK_API_KEY="your-api-key" python3 deepseek_search_mcp.py
```

For a persistent agent configuration, use the absolute path to `deepseek_search_mcp.py` and provide the key through the client's environment/secrets mechanism. Examples follow.

#### Hermes

Add an stdio MCP server using the Hermes CLI, then enter the script path and environment variable when prompted:

```sh
hermes mcp add deepseek-search --command "python3 /absolute/path/deepseek_search_mcp.py"
```

Set `DEEPSEEK_API_KEY` in the environment available to Hermes, then verify and enable the server:

```sh
hermes mcp list
hermes mcp test deepseek-search
```

#### OpenCode v2

The following configuration was tested with **OpenCode v2.0.29**. OpenCode v2 stores MCP servers under `mcp.servers` in its config. For example, add this entry to `~/.config/opencode/opencode.json` (global) or the project's `opencode.json`:

```json
{
  "mcp": {
    "servers": {
      "deepseek-search": {
        "type": "local",
        "command": ["python3", "/absolute/path/deepseek_search_mcp.py"],
        "environment": {
          "DEEPSEEK_API_KEY": "your-api-key"
        }
      }
    }
  }
}
```

Or register it through the OpenCode v2 CLI:

```sh
opencode mcp add deepseek-search \\
  --env DEEPSEEK_API_KEY=your-api-key \\
  -- python3 /absolute/path/deepseek_search_mcp.py
opencode mcp list
```

OpenCode v1 uses a different config shape (`mcp` entries directly, without the `servers` object). This example targets v2 only. Use a secret manager or a local untracked config instead of committing an API key.

#### Codex CLI

Add the server using the Codex CLI:

```sh
codex mcp add deepseek-search --env DEEPSEEK_API_KEY=your-api-key -- python3 /absolute/path/deepseek_search_mcp.py
```

Or add this to `~/.codex/config.toml`:

```toml
[mcp_servers.deepseek-search]
command = "python3"
args = ["/absolute/path/deepseek_search_mcp.py"]

[mcp_servers.deepseek-search.env]
DEEPSEEK_API_KEY = "your-api-key"
```

#### Claude Code

Register the server for the current project:

```sh
claude mcp add --transport stdio --scope project \
  --env DEEPSEEK_API_KEY=your-api-key \
  deepseek-search -- python3 /absolute/path/deepseek_search_mcp.py
```

Choose user scope instead of project scope to make the server available across projects. Use a local, untracked configuration or secret manager for API keys.

### For a person (without an agent)

Install nothing beyond Python. Set the key in the shell and run a search or fetch with any MCP-compatible desktop client. For example, with Claude Desktop, add an `mcpServers` entry to its configuration:

```json
{
  "mcpServers": {
    "deepseek-search": {
      "command": "python3",
      "args": ["/absolute/path/deepseek_search_mcp.py"],
      "env": {
        "DEEPSEEK_API_KEY": "your-api-key"
      }
    }
  }
}
```

Restart the client after changing its MCP configuration. Consult the client's documentation for the configuration file location and supported secret-variable syntax.

## Tools

### `deepseek_search`

Searches the web and returns ranked results, including title, URL, snippet, summary, relevance score, and authority tier.

Arguments:

- `query` (required): 1–128 characters; supports operators such as `site:`, `lang:`, `after:`, `before:`, quoted phrases, and exclusions.
- `count` (optional): 1–50, defaults to 10.
- `need_content` (optional): include extracted page content in results; defaults to `false`.
- `ori_question` (optional): original user question, up to 128 characters.
- `localization` (optional): IP address for localized results.

### `deepseek_fetch`

Fetches an HTTP or HTTPS page and returns its title and Markdown content.

## Billing and limits

DeepSeek bills Search and Fetch per successful request. Current pricing and rate limits are documented in the [DeepSeek Search & Fetch guide](https://api-docs.deepseek.com/guides/search). A search with `need_content: true` is one Search request; separately fetching pages makes additional Fetch requests.

## Local check

```sh
python3 test_smoke.py deepseek_search_mcp.py
```

## License

MIT. See [LICENSE](LICENSE).