Skip to main content
Glama
deepseek_search

deepseek_search

by numakkiyu

Codex DeepSeek Search

Adds web search and page fetch to Codex, using the DeepSeek Search / Fetch API as the search backend.

Once installed it shows up in Codex's plugin list next to the built-in web search. Codex uses it when the built-in search is unavailable or gives poor results, or when you ask for DeepSeek search explicitly.

English · 简体中文


What it looks like

In the Codex App plugin page you get the name, icon, three preset prompts, the MCP server, the skill, and the version and website fields.


Related MCP server: deepseek-websearch-mcp

Install

Requirements

Node.js

20 or newer (node -v)

Codex

CLI, desktop app or IDE extension

DeepSeek API key

create one at platform.deepseek.com

1. Download and install

git clone https://github.com/numakkiyu/codex-deepseek-search.git
cd codex-deepseek-search
node install.mjs

The installer registers the plugin marketplace, installs the plugin, and enables it in ~/.codex/config.toml. No key is needed for this step — it also creates the key file for you.

2. Add your key

Open ~/.codex/deepseek-search.env and put the key after the equals sign:

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

Save it. No restart needed — the plugin re-reads this file on the next tool call.

Don't want to hunt for the file: node install.mjs --open-config opens it in your editor.

3. Check it works

Start a new Codex session (/new), open /plugins, and confirm DeepSeek Search is enabled.

To check the whole chain from a terminal:

node doctor.mjs

It runs 14 checks: runtime, manifest files, which config file is active, the Codex install, the marketplace registration, the plugin cache, the MCP handshake, and the account balance.

Other installer options

node install.mjs --key sk-…          # write the key in the same run
node install.mjs --key-file key.txt  # read the key from a file
node install.mjs --configure         # only create the key file, print its path
node install.mjs --open-config       # create it and open it in your editor
node install.mjs --app-managed       # also register a user-level server (form-based key entry)
node install.mjs --print-config      # print all three routes as snippets
node install.mjs --verify-only       # verify only, change nothing
node install.mjs --no-verify         # skip the live check
node install.mjs --no-register       # do not touch the marketplace or plugin list
node install.mjs --uninstall         # remove plugin, marketplace and key file

The installer backs up config.toml before its first write, and writes nothing on a repeat run.


Usage

When it gets used

Codex reaches for this plugin when:

  1. the built-in web search fails, returns nothing, or returns irrelevant results;

  2. you ask for DeepSeek search explicitly;

  3. you need the full text of a specific page;

  4. it needs to work out why a search failed — it asks the status tool first.

Everything else still goes through the built-in search. When it switches, Codex says so in one sentence, so you know which engine produced the answer.

The three tools

The plugin registers one MCP server, deepseek_search, with three tools:

Tool

What it does

deepseek_web_search

Searches the web. Returns title, URL, short snippet, long summary, site name and icon, publication date, authority score and relevance score

deepseek_web_fetch

Fetches one page as Markdown

deepseek_search_status

Reports where the key came from, which config files exist, the endpoints, the protocol version and the account balance

Search parameters

Parameter

Type

Default

Notes

query

string, 1–128 chars

required

Supports the operators below

count

integer 1–50

10

Number of results; the per-request price does not depend on it

ori_question

string ≤128

—

Recommended. DeepSeek documents that it improves query understanding; measured effect on the result set is modest (mostly a re-rank)

localization

string

—

IP address for localized ranking; must be a valid IP

need_content

boolean

false

Also return page text, up to count pages per request

summary_max_chars

integer 200–8000

1200

Per-result summary cap, to control context size

Search operators

Passed through to the DeepSeek engine as-is:

Operator

Example

Meaning

site:

DeepSeek site:github.com

Only this site; combine several with OR

-site:

DeepSeek -site:example.com

Exclude a site

-word

DeepSeek -advertisement

Exclude results containing a word

"phrase"

DeepSeek "release notes"

Exact phrase; prefix with - to exclude

lang:

DeepSeek lang:en,zh

Restrict language

after: / before:

DeepSeek after:2025-01-01

Restrict publication date

Examples

Just ask in Codex:

  • Search with DeepSeek for the latest DeepSeek API changes

  • Use DeepSeek to find the MCP spec, but only on modelcontextprotocol.io

  • Read this page in full and summarize it: https://example.com/article


How it works

Pieces

The plugin is three parts, all under plugins/deepseek-search/:

plugins/deepseek-search/
├── .codex-plugin/plugin.json   what Codex reads: name, icons, skills, MCP declaration
├── .mcp.json                   how to start the server: command, args, timeouts, env allowlist
├── server/                     the MCP server itself — plain Node.js, no dependencies
│   ├── server.mjs              protocol handling + turns results into text and structured data
│   ├── deepseek-client.mjs     calls the DeepSeek API: retries, cache, rate limit, error mapping
│   ├── config.mjs              finds the key, merges config layers, watches the files
│   └── tools.mjs               parameter and response schemas for the three tools
└── skills/deepseek-search/
    └── SKILL.md                tells Codex when to use it and how to search well

After installation Codex copies the plugin to ~/.codex/plugins/cache/…/<version>/ and runs it from there. Because the path contains the version, you must reinstall after an upgrade — otherwise Codex keeps running the old copy.

One search, end to end

flowchart TD
    A[User asks a question] --> B[Codex model]
    B -->|built-in search unavailable, or user asked| C[calls deepseek_web_search]
    C --> D[deepseek_search MCP server]
    D --> E{read the API key}
    E -->|environment variable| F[send request]
    E -->|config file| F
    E -->|neither| G[return a missing-key error with the file path]
    F --> H[DeepSeek Search API]
    H --> I[clean up results: decode site names, trim summaries]
    I --> J[return to Codex]
    J --> B

On a tools/call request the server calls POST /v1/tools/search, then returns two things together:

  • content — text for the model to read (a Markdown list);

  • structuredContent — fields for programs, matching the schema declared in tools.mjs.

Where the key comes from

First source with a value wins:

  1. DEEPSEEK_API_KEY (or DS_API_KEY) in the environment

  2. A config file, in this order:

    • $DEEPSEEK_SEARCH_ENV_FILE (if set)

    • $PLUGIN_DATA/deepseek-search.env (the per-plugin data directory Codex injects)

    • ~/.codex/deepseek-search.env (what the installer writes)

    • ~/.deepseek-search.env

    • <plugin dir>/.env

  3. The refs: block in ~/.dsh/.credentials.yaml

The files are re-checked for changes before every tool call, so an edit takes effect immediately. deepseek_search_status tells you which layer is active and the absolute paths of all candidates.

MCP protocol

One server, two protocol eras:

Client

How it opens

Response shape

Legacy (2025-11-25 and earlier)

sends initialize first

legacy shape, no resultType

Modern (2026-07-28)

no handshake; version travels per request in params._meta

includes resultType, cacheScope, ttlMs

Which era applies is decided by how the client opens the connection.

How errors come back

Two kinds, on purpose:

Tool execution errors (isError: true) — problems the model can understand and correct, such as a bad parameter, an invalid key, or an unreachable page. These carry an explanation, so the model can adjust and retry.

JSON-RPC protocol errors (with a code) — the request itself is malformed: unknown tool, bad JSON, unsupported protocol version. The model cannot fix these, so the host gets an error code.

Status

code

Meaning

What the model is told

—

missing_api_key

No key configured

absolute paths of the three candidate files

400

bad_request

Invalid parameter

which field is wrong

401

invalid_key

Invalid key

which file the key came from, and which to edit

402

balance_exhausted

Balance exhausted

current balance and the top-up page

403

forbidden

Blocked by safety policy (fetch)

try a different URL

404

page_not_found

Page unreachable or no body

try a different search result

408

timeout

Upstream read timeout

already retried

413

payload_too_large

Body over 160 KiB

lower count, or turn off need_content

429

rate_limited

Rate limited

Search 100 QPS, Fetch 25 QPS per account

5xx

server_error

Server error

already retried automatically

Errors carry both forms at once: readable text for the model, and structuredContent.error.code for programs (the values in the table above). That lets a front end recognise "out of credit" and offer a top-up without parsing prose.

408, 429 and every 5xx are retried with exponential backoff and jitter. Other 4xx responses are not retried.

Empty results are relaxed automatically

DeepSeek does not bill a search that returns no results. The server uses that: when the first search comes back empty it relaxes the query itself instead of handing the job back to the model — first dropping after: / before:, then site: / -site:, then quoted phrases. It stops as soon as a step returns something.

The response reports relaxed, attempts and relaxations, so you can tell "nothing matches the strict query" from "nothing matches at all". Set DEEPSEEK_SEARCH_AUTO_RELAX=0 to turn it off.

How the DeepSeek API actually behaves

Measured, not taken from the docs. Where the two disagree, the plugin follows what the API does.

Item

Documentation

Measured

Handling

site_name

site name

about half are hex strings (e5a4aee5b9bfe7bd91 is 央广网)

validated decode, else left as-is

summary length

usually 600–800 chars

median 1739, max over 5600

capped by summary_max_chars, default 1200

site_icon

the site's favicon

always cdn.deepseek.com/site-icons/<domain>

passed through

authority

0–4, ≥3 means highly authoritative, -1 unknown

~96% of results score 3 or higher

semantics kept; used for ordering and citation choice, not as a filter

rerank_score

0–3, ≥1.5 means high quality

~89% clear 1.5; normal range 1.3–2.7

same: documented semantics kept, used as relative ordering within one response

error field

code identifies the error

code is constant; type is what varies

classified by type

request body limit

only "413 too large"

exactly 163840 bytes

stated in the 413 message

retry scope

408, 429, 5xx

should cover all 5xx

checks >= 500

rate-limit headers

may include Retry-After

none are returned

plain exponential backoff

fetch body

Markdown

~77 escaped characters per 1000

unescaped before returning

same query

stable results

URL overlap ~4/10 across three calls; top hit stable

does not promise identical results

error pages

page errors surface

a site's "page not found" can arrive as HTTP 200

flagged as suspectedErrorPage

deduplication

—

1 duplicate in 300 results

not implemented

Two more measurements shaped the defaults:

  • count from 1 to 50 barely changes latency (634 ms → 543 ms), and pricing is per request — so a larger count does not cost more.

  • One need_content=true request returns up to count full pages, which is cheaper than fetching them one by one and gives cleaner text.

Limits and caching

  • Fetch goes through a token bucket, 20 QPS by default (the account cap is 25), with at most 8 requests in flight.

  • Identical queries hit an in-process cache: 120 seconds, 64 entries. It only reduces latency; it is not a consistency guarantee.

  • No per-domain serialization is needed — 20–24 concurrent fetches against one domain produced no 429s.


How it differs from a plain DeepSeek MCP server

The existing DeepSeek search MCP servers all work, and do broadly the same thing. The differences are:

Item

Plain MCP server

This project

Knows when to be used

no, the model decides

yes, stated in SKILL.md

MCP protocol versions

usually one

both 2026-07-28 and legacy

Diagnostic tool

usually none

doctor.mjs, 14 checks

Where the key lives

usually config.toml

a separate file you can edit any time

Follows the API's real behaviour

mostly the docs

measured behaviour (see above)

If you only need an MCP server and don't mind editing config.toml yourself, any of them will do.


FAQ

Installed, but nothing shows in /plugins Check that node install.mjs finished without errors, then start a new session. Plugins load when Codex starts.

It says no API key is configured Run node doctor.mjs. It prints the absolute paths of the three candidate files and marks which exists and which is writable.

Still 401 after adding a key You probably edited a file that isn't the active one. Call the deepseek_search_status tool and look at keySource.

It says the balance is exhausted Top up at platform.deepseek.com. The status tool shows the balance.

doctor reports Marketplace path failed The marketplace still points at another directory, usually because the checkout moved. Run node install.mjs again — it rewrites that single line and nothing else.

The plugin cache is locked A Codex instance is running. Close it and re-run the installer.


License

MIT.

Not affiliated with DeepSeek or OpenAI. "DeepSeek", the DeepSeek mark and "Codex" belong to their respective owners.


DeepSeek Search API docs · MCP specification 2026-07-28 · DeepSeek platform

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables agents to run web searches with query operators and to fetch web pages as Markdown through DeepSeek's native Search/Fetch JSON API. It acts as a fallback for hosts whose built-in web tools are unavailable or return errors such as HTTP 403, rather than retrying them repeatedly.
      2
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP-capable AI clients to run web searches through DeepSeek's search engine and fetch individual webpages as Markdown. Search results include relevance scores, authority, and publication times, and support advanced query syntax such as site:, lang:, and date filters.
      2
      51 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to run web searches and fetch individual web pages as Markdown through DeepSeek's official Search/Fetch API, with freshness filtering, structured metadata such as publish date, authority and rerank scores, and raw structured output.
      89 npm
      4
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to run web searches and fetch HTTP(S) pages as Markdown via the DeepSeek Search/Fetch API, returning titles, URLs, summaries, publication dates, authority scores, and optional page content. Supports advanced query operators like site:, exact phrases, exclusion terms, lang:, and date-range filters, with retries, timeouts, and structured errors.
      1
      MIT