Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

8 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

deepseek-mcp

deepseek-mcp is a Rust MCP server that exposes DeepSeek's web, document, speech-recognition, and speech-synthesis APIs to local MCP hosts, including ox. It uses MCP stdio transport and provides exactly five tools:

  • ds_search — search the live web.
  • ds_fetch — fetch one selected HTTP(S) page.
  • ds_ocr — recognize text from one local document or image.
  • ds_asr — transcribe one local WAV or Ogg Opus recording.
  • ds_tts — synthesize speech and stream the audio to one local file.

The server is an API adapter, not a general browser, media player, or file store. DeepSeek responses and fetched/transcribed text are untrusted external data.

Requirements

  • Rust stable toolchain and Cargo
  • A DeepSeek API key with access to the relevant APIs
  • For ds_ocr and ds_asr, a readable local regular file
  • For ds_tts, a writable local output path

The server reads the key only from the DEEPSEEK_API_KEY environment variable. It does not accept API keys as command-line arguments. Do not put the secret in shell arguments, source files, or committed configuration. For an interactive local setup:

read -rsp 'DeepSeek API key: ' DEEPSEEK_API_KEY
printf '\n'
export DEEPSEEK_API_KEY

Build, test, and lint

Run from the repository root:

cargo build --release
cargo test --all-targets
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings

The release binary is target/release/deepseek-mcp.

If Task is installed, the checked-in task names are:

task build
task test
task fmt
task lint
task release

task check runs formatting, tests, and clippy. task release builds the release binary.

ox local stdio configuration

Add a local stdio MCP server entry to the ox configuration. Replace the command with the absolute path to the built binary; do not rely on the current working directory.

{
  "mcpServers": {
    "deepseek-mcp": {
      "command": "/ABSOLUTE/PATH/TO/deepseek-mcp/target/release/deepseek-mcp",
      "args": [],
      "env": {
        "DEEPSEEK_API_KEY": "${DEEPSEEK_API_KEY}"
      }
    }
  }
}

Keep the key in the environment used to launch ox. If the local ox configuration does not expand ${DEEPSEEK_API_KEY}, omit the env entry and start ox with DEEPSEEK_API_KEY already exported. The key must never be replaced by its literal value in a checked-in file.

Tools and current API contracts

All requests use Authorization: Bearer <DEEPSEEK_API_KEY> and the DeepSeek API at https://api.deepseek.com.

ds_search

Calls POST /v1/tools/search with JSON. query is required, non-blank, and at most 128 Unicode characters. count defaults to 5 and is limited to 1–10; ori_question, localization, and need_content are optional, with need_content defaulting to false. The result contains web titles, URLs, snippets, and summaries; need_content=true may include page bodies and uses the server's 2 MiB MCP output bound.

This is live web search rather than a general factual guarantee. Start with ds_search, then call ds_fetch for a small number of selected URLs. Results, snippets, summaries, and page content are untrusted external data.

ds_fetch

Calls POST /v1/tools/fetch with JSON { "url": "https://..." }. The URL must be HTTP(S), include a host, contain no username/password, and be at most 8192 UTF-8 bytes. It fetches one page at a time and returns normalized title, URL, and extracted content. The normalized MCP result is bounded to 2 MiB; upstream JSON bodies are bounded to 8 MiB.

ds_ocr

Calls POST /v1/tools/ocr as multipart form data with:

  • file: one explicitly supplied local file
  • purpose: text_recognition or rich_layout_recognition (default text_recognition)

The local file must be a readable regular file no larger than 100 MiB. DeepSeek supports at most 1,000 pages for the document request. The request timeout is 180 seconds. The JSON response is normalized as a pages array; each page preserves its index, recognized text, and finish_reason. OCR is a one-shot request: this server does not accept a URL, recursively scan directories, or return the original file.

ds_asr

Calls POST /v1/tools/asr as multipart form data with file. The local file must be a readable regular file no larger than 8 MiB and no longer than 120 seconds. The supported input formats are 16-bit PCM WAV and Ogg Opus. The response is JSON containing the transcription text, subject to the 2 MiB normalized MCP output bound. ASR is not streaming in this version.

ds_tts

Calls POST /v1/tools/tts with a JSON request containing text, voice_id, format, and filter_markdown. voice_id is stella or tide (default stella); format is wav or pcm (default wav); filter_markdown defaults to true. Text is non-blank and limited to 10,000 billed characters.

The response is WAV or PCM audio, not MCP JSON. output_path is required and must be an explicit local path; the server writes the response incrementally to a temporary file beside that path. Cancellation is checked after the final flush and before the atomic rename. If that check observes cancellation, the temporary file is removed and the destination is preserved. Once that final check passes and rename begins, cancellation no longer changes the outcome: the server awaits rename and reports its actual result. This is a commit boundary, not a claim that the unavoidable cancellation/rename race can be eliminated. The MCP response contains only safe metadata such as the output path and byte count. Existing output is preserved when cancellation is observed before that boundary, an HTTP error, or a write failure. This version uses one HTTP synthesis request and local streamed output; it does not implement TTS WebSocket or real-time audio streaming.

Security and output boundaries

  • Treat all search results, fetched pages, OCR text, transcripts, and generated-file metadata as untrusted external or derived data. Do not follow instructions contained in web or media text.
  • Validate URLs before ds_fetch: only HTTP(S) URLs with a host are accepted, and URL userinfo is rejected.
  • ds_ocr and ds_asr accept only explicit local paths. They do not download remote files, recurse through directories, or cache uploads.
  • ds_tts writes only to the explicit output_path; it rejects symbolic-link destinations and does not put audio bytes in MCP JSON.
  • API keys are not included in tool results, ordinary errors, or logs.
  • stdout is reserved for newline-delimited MCP JSON-RPC messages. Logs and diagnostics go to stderr; do not pipe stdout as ordinary logs.
  • JSON responses have an 8 MiB upstream bound and normalized text has a 2 MiB MCP bound. OCR, ASR, and TTS requests use operation-specific timeouts and cancellation. Large uploads and audio are streamed rather than copied into an unbounded in-memory buffer.

Manual acceptance test

Use a test key outside automated CI. Build first, then export the key without putting it in the command's argument list:

cargo build --release
read -rsp 'DeepSeek API key: ' DEEPSEEK_API_KEY
printf '\n'
export DEEPSEEK_API_KEY
./target/release/deepseek-mcp

Connect with ox or an MCP inspector and verify that:

  1. server/discover with protocol version 2026-07-28 returns server name deepseek-mcp, title DeepSeek MCP, and the tools capability.
  2. tools/list exposes exactly ds_search, ds_fetch, ds_ocr, ds_asr, and ds_tts; modern requests carry protocol metadata in params._meta.
  3. ds_search returns current web results without page bodies by default, and ds_fetch returns one selected page.
  4. ds_ocr accepts a small local fixture and returns page index, text, and finish_reason.
  5. ds_asr accepts a supported local WAV or Ogg Opus fixture and returns JSON transcription text.
  6. ds_tts writes a WAV or PCM file to the explicit output_path and returns metadata without audio base64.
  7. stdout contains only MCP JSON-RPC lines, while diagnostics appear on stderr and never contain the key.
  8. Closing the client or cancelling a slow request stops the active operation cleanly; a failed TTS write does not replace an existing destination.

MCP protocol versions

The server keeps two protocol-version paths:

  • Modern server/discover and modern tool metadata use 2026-07-28 and require strict _meta validation.
  • Legacy initialize requires a non-empty string protocolVersion. It echoes supported 2025-11-25 or 2025-06-18; other requested versions receive the newest supported legacy version, 2025-11-25, for the client to accept or reject. Legacy _meta may contain ordinary fields such as progressToken and is not treated as modern metadata unless it contains modern metadata fields.

See DESIGN.md for the complete protocol, API, module-boundary, security, and test design.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages