deepseek_search
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 ( |
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.mjsThe 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-xxxxxxxxxxxxxxxxxxxxxxxxSave 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-configopens 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.mjsIt 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 fileThe 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:
the built-in web search fails, returns nothing, or returns irrelevant results;
you ask for DeepSeek search explicitly;
you need the full text of a specific page;
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 |
| Searches the web. Returns title, URL, short snippet, long summary, site name and icon, publication date, authority score and relevance score |
| Fetches one page as Markdown |
| 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 |
| string, 1–128 chars | required | Supports the operators below |
| integer 1–50 | 10 | Number of results; the per-request price does not depend on it |
| string ≤128 | — | Recommended. DeepSeek documents that it improves query understanding; measured effect on the result set is modest (mostly a re-rank) |
| string | — | IP address for localized ranking; must be a valid IP |
| boolean | false | Also return page text, up to |
| 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 |
|
| Only this site; combine several with |
|
| Exclude a site |
|
| Exclude results containing a word |
|
| Exact phrase; prefix with |
|
| Restrict language |
|
| 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 wellAfter 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 --> BOn 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 intools.mjs.
Where the key comes from
First source with a value wins:
DEEPSEEK_API_KEY(orDS_API_KEY) in the environmentA 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
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 | legacy shape, no |
Modern (2026-07-28) | no handshake; version travels per request in | includes |
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 |
| Meaning | What the model is told |
— |
| No key configured | absolute paths of the three candidate files |
400 |
| Invalid parameter | which field is wrong |
401 |
| Invalid key | which file the key came from, and which to edit |
402 |
| Balance exhausted | current balance and the top-up page |
403 |
| Blocked by safety policy (fetch) | try a different URL |
404 |
| Page unreachable or no body | try a different search result |
408 |
| Upstream read timeout | already retried |
413 |
| Body over 160 KiB | lower |
429 |
| Rate limited | Search 100 QPS, Fetch 25 QPS per account |
5xx |
| 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 | about half are hex strings ( | validated decode, else left as-is |
| usually 600–800 chars | median 1739, max over 5600 | capped by |
| the site's favicon | always | passed through |
| 0–4, ≥3 means highly authoritative, | ~96% of results score 3 or higher | semantics kept; used for ordering and citation choice, not as a filter |
| 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 |
|
| classified by |
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 |
rate-limit headers | may include | 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 |
deduplication | — | 1 duplicate in 300 results | not implemented |
Two more measurements shaped the defaults:
countfrom 1 to 50 barely changes latency (634 ms → 543 ms), and pricing is per request — so a largercountdoes not cost more.One
need_content=truerequest returns up tocountfull 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 |
MCP protocol versions | usually one | both 2026-07-28 and legacy |
Diagnostic tool | usually none |
|
Where the key lives | usually | 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Web search and page fetch for AI agents. Results come from a shared cache; cached calls cost less.
Web search, scraping, Google Trends and data lookups. Paid per call in USDC on Base via x402.
Web search and page extraction for AI agents, paid per call with x402 (USDC on Base).
Web search, fetch, extract, and research for AI agents. Markdown output + AI-synthesized answers.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables 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.21MIT
- AlicenseAqualityBmaintenanceEnables 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.251 npmApache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables 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 npm4MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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.1MIT