1 line
9.2 KiB
JSON
1 line
9.2 KiB
JSON
{"repo": "arizen-dev/deepseek-mcp", "files": {"README.md": {"d95f9f8dd32c0d6474e1fb7d55c49594f3fd2584": {"t": 1785674503.572586, "n": 8765, "h": "6688abe5c7589183", "c": "# deepseek-mcp\n\n[](LICENSE)\n[](pyproject.toml)\n[](https://github.com/arizen-dev/deepseek-mcp/actions/workflows/test.yml)\n\nUse DeepSeek from Claude Code, Codex, or any MCP-compatible client as a small, cheap supervised worker.\n\n`deepseek-mcp` is a tiny stdio MCP server with two tools:\n\n```text\ndeepseek(prompt, system?) — fast, cheap, non-thinking (flash)\nadvise(prompt, system?, effort?) — deep reasoning (pro + thinking)\n```\n\nIt is built for bounded tasks where another model can reduce mechanical load:\n\n- classify inboxes, tickets, logs, notes, or docs;\n- summarize packets;\n- turn messy text into JSON or tables;\n- populate templates;\n- generate first-pass mechanical edits;\n- produce reviewable candidate output for a human or primary agent.\n\nIt is not built for autonomous architecture, security policy, final client prose, or decisions where the hard part is judgment.\n\n## Quickstart\n\n### 1. Install\n\nZero-install with `uvx`:\n\n```bash\nDEEPSEEK_API_KEY=\"sk-...\" uvx deepseek-mcp-server\n```\n\nOr install persistently:\n\n```bash\npip install \"git+https://github.com/arizen-dev/deepseek-mcp.git\"\n```\n\nOr clone and install locally:\n\n```bash\ngit clone https://github.com/arizen-dev/deepseek-mcp.git\ncd deepseek-mcp\npip install -e .\n```\n\n### 2. Add your DeepSeek key\n\nCreate an API key at:\n\n```text\nhttps://platform.deepseek.com/api_keys\n```\n\nThen export it:\n\n```bash\nexport DEEPSEEK_API_KEY=\"sk-...\"\n```\n\nFor Claude Code, the lowest-friction setup is to put the key in your global settings:\n\n```json\n{\n \"env\": {\n \"DEEPSEEK_API_KEY\": \"sk-...\"\n }\n}\n```\n\nPath:\n\n```text\n~/.claude/settings.json\n```\n\nMCP servers are started when the client launches, so restart Claude Code or Codex after changing env/config.\n\n### 3. Configure MCP\n\nIf you installed via pip (or uvx), use the installed command directly:\n\n```json\n{\n \"mcpServers\": {\n \"deepseek\": {\n \"command\": \"deepseek-mcp-server\",\n \"args\": [],\n \"env\": {\n \"DEEPSEEK_API_KEY\": \"${DEEPSEEK_API_KEY}\"\n }\n }\n }\n}\n```\n\nIf you cloned the repo, point to the script directly:\n\n```json\n{\n \"mcpServers\": {\n \"deepseek\": {\n \"command\": \"python3\",\n \"args\": [\"/absolute/path/to/deepseek-mcp/deepseek_mcp_server.py\"],\n \"env\": {\n \"DEEPSEEK_API_KEY\": \"${DEEPSEEK_API_KEY}\"\n }\n }\n }\n}\n```\n\nAfter restart, `/mcp` should show a `deepseek` server.\n\nIn Claude Code, the tool names are:\n\n```text\nmcp__deepseek__deepseek — flash (fast, mechanical)\nmcp__deepseek__advise — pro (deep reasoning)\n```\n\n## Codex\n\nFor Codex, add a global MCP server in `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.deepseekWorker]\ncommand = \"deepseek-mcp-server\"\nargs = []\n\n[mcp_servers.deepseekWorker.env]\nDEEPSEEK_API_KEY = \"sk-...\"\n```\n\nCodex TOML does not expand `\"${DEEPSEEK_API_KEY}\"` in the same way Claude project MCP configs do. Put the key directly in the TOML env block or use whatever secret mechanism your Codex environment supports.\n\n## Demo\n\nPrompt:\n\n```text\nClassify these files into doc / code / config. Return JSON only:\n- README.md\n- pyproject.toml\n- src/deepseek_mcp/server.py\n```\n\nExample output:\n\n```json\n[\n {\"file\": \"README.md\", \"type\": \"doc\"},\n {\"file\": \"pyproject.toml\", \"type\": \"config\"},\n {\"file\": \"src/deepseek_mcp/server.py\", \"type\": \"code\"}\n]\n```\n\nThe server appends lightweight metadata:\n\n```text\n---\n_deepseek · model=deepseek-v4-flash latency=18.42s tokens=52+74 cost=$0.0001_\n```\n\nLatency depends heavily on prompt size, model, network, and API load. Treat benchmark numbers as directional, not a guarantee.\n\n## CLI\n\nAfter installing, you can use the CLI for smoke tests and one-shot calls:\n\n```bash\n# Validate setup\npython -m deepseek_mcp check\n\n# One-shot flash call\npython -m deepseek_mcp run \"Classify: urgent / later — 'Server down in prod'\"\n\n# Advisor call with deep reasoning\npython -m deepseek_mcp advise \"Should we build or buy analytics?\" --effort max\n```\n\nExit codes: 0 = success, 1 = API error, 2 = missing key.\n\n## Models\n\n| Tool | Model | Mode | Best for |\n|------|-------|------|----------|\n| `deepseek` | deepseek-v4-flash | Non-thinking | Classification, extraction, formatting, mechanical edits |\n| `advise` | deepseek-v4-pro | Thinking (effort: medium/high/max) | Architecture, tradeoffs, second opinions, ambiguity |\n\n## Cost\n\nPer-call cost depends on token count and model. Pricing per [api.deepseek.com](https://api.deepseek.com) (checked 2026-04-30).\n\n| Model | Input (miss) | Input (cache hit) | Output |\n|-------|-------------|-------------------|--------|\n| `deepseek-v4-flash` | $0.14/1M | $0.0028/1M | $0.28/1M |\n| `deepseek-v4-pro` | $0.435/1M¹ | $0.0036/1M¹ | $0.87/1M¹ |\n\n¹ Pro pricing is 75% off until 2026-05-31. Non-discounted: $1.74/$0.0145/$3.48.\n\n**Typical per-call cost (cache miss):**\n\n| Task | Flash | Pro |\n|------|-------|-----|\n| Small (~1K in + ~0.5K out) | ~$0.0003 | ~$0.0009 |\n| Medium (~4K in + ~2K out) | ~$0.001 | ~$0.003 |\n\nEach response footer includes an estimated `cost=$...` based on token usage.\n\n## Environment variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `DEEPSEEK_API_KEY` | — | Required. Your DeepSeek API key. |\n| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | API base URL (change for proxy/compatible providers). |\n| `DEEPSEEK_MCP_LOG` | (unset) | Set to `1` to log call metadata to `~/.deepseek-mcp/calls.jsonl` (no prompts logged). |\n\n## When to use it\n\nGood:\n\n- \"Classify these 200 filenames. Mark uncertainty.\"\n- \"Turn this rough note into a CSV table.\"\n- \"Extract all TODOs and group them by owner.\"\n- \"Create candidate JSON from this messy list. Use null for missing values.\"\n- \"Summarize this packet for review; do not make decisions.\"\n\nBad:\n\n- \"Design my architecture.\"\n- \"Write the final client email.\"\n- \"Decide whether this is secure.\"\n- \"Resolve this ambiguous business rule.\"\n- \"Publish this reply directly.\"\n\nUse it like a fast junior analyst whose work you will review, not like an owner.\n\n## How it works\n\nThe server:\n\n1. reads JSON-RPC messages from stdin;\n2. exposes two MCP tools: `deepseek` (flash, non-thinking) and `advise` (pro, thinking);\n3. sends your prompt to DeepSeek's OpenAI-compatible chat completions API;\n4. streams the response;\n5. returns the text plus model, latency, token, and cost metadata.\n\nThere is no database, no background daemon, no local web server, and no file-system access beyond the MCP client starting the process.\n\n## Smoke test\n\nAfter installing:\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' \\\n | DEEPSEEK_API_KEY=\"sk-...\" deepseek-mcp-server\n```\n\nYou should see a JSON response with two tools (`deepseek` + `advise`).\n\nThen test a real call:\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\\\n \"params\":{\"name\":\"deepseek\",\"arguments\":{\"prompt\":\"Return exactly: ok\"}}}' \\\n | DEEPSEEK_API_KEY=\"sk-...\" deepseek-mcp-server\n```\n\n## Examples\n\nSee [examples/](examples/) for real prompt templates:\n- [flash_classify.md](examples/flash_classify.md) — inbox triage\n- [advise_architecture.md](examples/advise_architecture.md) — architecture decision\n- [advise_tradeoff.md](examples/advise_tradeoff.md) — build vs buy\n\n## Benchmark\n\nSee [docs/benchmark.md](docs/benchmark.md) for validation observations and usage guidance.\n\n## Development\n\n```bash\npip install -e \".[dev]\"\npip install -r requirements-dev.txt # alternative\npython -m pytest\n```\n\n## Compatible endpoints\n\n`deepseek-mcp` works with any OpenAI-compatible API. Set `DEEPSEEK_BASE_URL` to point elsewhere:\n\n| Provider | `DEEPSEEK_BASE_URL` | Notes |\n|----------|---------------------|-------|\n| DeepSeek | `https://api.deepseek.com` | Default |\n| Google Gemini | `https://generativelanguage.googleapis.com/v1beta/openai/` | Requires Gemini API key; models like `gemini-2.5-flash` |\n| Ollama (local) | `http://localhost:11434/v1` | Run any local model; e.g. `llama3`, `qwen2.5` |\n| vLLM (self-hosted) | `http://localhost:8000/v1` | For self-hosted open-weight models |\n| Mistral API | `https://api.mistral.ai/v1` | Requires Mistral API key |\n\n## Security notes\n\n- The worker returns text only. It cannot call tools, write files, or access your repo. Output lands in the primary model's context — you review before anything is used.\n- Do not commit API keys.\n- Prefer client/global env injection over hardcoding keys in project repos.\n- Treat model output as untrusted candidate text.\n- Do not give the tool access to secrets you would not paste into DeepSeek directly.\n- Review output before it reaches users, customers, production systems, or public channels.\n\n## License\n\nMIT\n"}}}} |