Skip to main content
Glama
penn0312

seekpeek

by penn0312
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

seekpeek

Give your AI agents eyes on the live web — search it, or peek at any page.

seekpeek is a Model Context Protocol server that wraps the DeepSeek Search & Fetch API (/v1/tools/search, /v1/tools/fetch) into tools any MCP host can call: Claude Code, Claude Desktop, Cursor, VS Code, Codex, Cline, Windsurf, and the rest.

English · 简体中文

CI

Why

Most agents are frozen at their training cutoff. DeepSeek's Search API is a good, cheap way to thaw them out: a self-built index, structured results carrying a relevance rerank score and an authority rating, a short snippet for humans and a long summary written for models.

seekpeek turns that into tools a model can actually use well, and handles the boring parts:

The boring part

What seekpeek does

Context blowups

Caps page bodies with a visible [truncated: …] marker instead of silently dumping 100k characters

Random 429s

Client-side rate limiting (the account allows 5 QPS) plus exponential backoff with jitter on 408/429/5xx

Cryptic failures

401/402/403/404 become paragraphs the model can read and act on

N+1 round trips

fetch_many fetches up to ten pages concurrently behind a single tool call

Related MCP server: free-web-mcp

Features

  • 🔎 search — web search with the full DeepSeek query syntax (site:, -site:, lang:, after:, before:, phrases, exclusions)

  • 📄 fetch — any URL → clean Markdown

  • 📚 fetch_many — batch fetching, concurrency-limited, per-URL error reporting

  • 🧠 Model-friendly output — Markdown by default, raw JSON on request; prefers the long summary over the human snippet

  • 🧭 Guided prompt + resource — a web-research prompt and a seekpeek://search-syntax cheatsheet for hosts that support them

  • 🖥️ Two transports — stdio for local hosts, streamable-http for shared or remote deployments

  • 🧰 Also a CLI — seekpeek search "…", seekpeek fetch <url>, seekpeek doctor

Quick start

You need a DeepSeek API key: https://platform.deepseek.com/api_keys.

1. Add it to your MCP host

Claude Code

claude mcp add seekpeek --env DEEPSEEK_API_KEY=sk-your-key -- uvx seekpeek

Any JSON-configured host (Claude Desktop, Cursor, VS Code, Cline, Windsurf, …) — add this to the mcpServers block:

{
  "mcpServers": {
    "seekpeek": {
      "command": "uvx",
      "args": ["seekpeek"],
      "env": {
        "DEEPSEEK_API_KEY": "sk-your-key"
      }
    }
  }
}

Not on PyPI yet? Install straight from Git instead:

{
  "mcpServers": {
    "seekpeek": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/penn0312/seekpeek", "seekpeek"],
      "env": { "DEEPSEEK_API_KEY": "sk-your-key" }
    }
  }
}

2. Ask something that needs the web

"Search for the latest DeepSeek model release and summarise what changed."

The model calls seekpeek → search, then fetch (or fetch_many) whichever pages it wants in full.

Remote / HTTP deployment

DEEPSEEK_API_KEY=sk-... seekpeek --transport streamable-http --host 127.0.0.1 --port 8765
# MCP endpoint: http://127.0.0.1:8765/mcp

Exposed beyond localhost? Put it behind a reverse proxy with authentication — seekpeek itself is unauthenticated and spends your DeepSeek quota.

Tools

search

search(
  query: str,                            # 1-128 chars, supports the operators below
  count: int = 10,                       # 1-50
  ori_question: str | None = None,       # the user's original question, sharpens intent matching
  need_content: bool = False,            # also return full page text
  localization: str | None = None,       # IP address used to prefer localised results
  max_content_chars: int = 12000,        # per-result body cap, 0 = unlimited
  response_format: "markdown" | "json" = "markdown",
) -> str

Real output (need_content=true, bodies capped at 200 chars for this sample):

# seekpeek · search

Query: `DeepSeek 模型 site:github.com OR site:huggingface.co lang:zh` — 2 results, bodies capped at 200 chars each

## 1. DeepSeek V4 模型发布

- URL: https://example.com/deepseek-v4
- Relevance: 2.4/3.0 (high-quality) · Authority: 3/4 (authoritative) · Published: 2026-06-01 · Site: Example News

DeepSeek 发布了 V4 模型。此次发布改进了工具调用与长上下文能力，适合 Agent 工作流。

**Page content** (from `https://example.com/deepseek-v4`):

DeepSeek V4 现已正式上线……DeepSeek V4 现已正式上线……DeepSeek V4 现已正式上线……DeepSeek V4 现已正式上线……

… [truncated: 600 more characters]

## 2. Some older thread

- URL: https://forum.example.org/t/123
- Relevance: 0.8/3.0 · Authority: 1/4 · Published: 2024-11-02

A discussion from last year.

Every result is ranked. rerank_score ≥ 1.5 is flagged high-quality, authority ≥ 3 is flagged authoritative, so the model can triage before spending context on a page. The long summary (written for models) is used when available, snippet only as a fallback.

fetch

fetch(url: str, max_chars: int = 12000, response_format: "markdown" | "json" = "markdown") -> str

Returns the page title plus its Markdown body. max_chars=0 disables truncation. Bare hosts are accepted (example.com/doc), and the URL is validated before it costs you a request.

fetch_many

fetch_many(urls: list[str], max_chars: int = 12000, response_format: … ) -> str

Up to 10 URLs, fetched concurrently under the shared rate limiter. One dead link never fails the call:

# seekpeek · fetch_many (1/2 succeeded)

## 1. Example article

- URL: https://example.com/article

# Example article

Article content.

## 2. https://broken.example.com/article

Failed: No usable content for https://broken.example.com/article (404). The page may be unreachable,
blocked by the site, served as an unsupported content type, or contain no extractable Markdown.

Prompt & resource

  • Prompt web-research — takes a topic and a depth (quick / standard / deep), and returns a research brief that teaches the model the query syntax and when to fetch.

  • Resource seekpeek://search-syntax — the operator cheatsheet and result-field thresholds as Markdown.

Search syntax

Passed straight through to DeepSeek; combine as many operators as you like in one query.

Operator

Example

Effect

site:

DeepSeek site:github.com

Restrict to a site. Several: site:github.com OR site:huggingface.co

-site:

DeepSeek -site:example.com

Exclude sites

-

DeepSeek -广告

Exclude pages containing a keyword

-"…"

DeepSeek -"release notes"

Exclude an exact phrase

"…"

DeepSeek "精确短语"

Exact phrase match

lang:

DeepSeek lang:zh,en

Restrict languages

after:

DeepSeek after:2025-01-01

Published after a date (after:2025 works too)

before:

DeepSeek before:2026-06

Published before a date

Configuration

Variable

Default

Meaning

DEEPSEEK_API_KEY

—

Required. Your DeepSeek API key

DEEPSEEK_BASE_URL

https://api.deepseek.com

API base URL (proxy or gateway)

SEEKPEEK_TIMEOUT

60

Per-request timeout in seconds

SEEKPEEK_MAX_RETRIES

2

Retries on 408 / 429 / 5xx

SEEKPEEK_SEARCH_QPS

5

Client-side search rate limit

SEEKPEEK_FETCH_QPS

5

Client-side fetch rate limit

seekpeek doctor prints the effective configuration and probes the API:

$ seekpeek doctor
seekpeek 0.1.0 — configuration
  DEEPSEEK_API_KEY      sk-abc…f123
  DEEPSEEK_BASE_URL     https://api.deepseek.com
  SEEKPEEK_TIMEOUT      60s
  SEEKPEEK_MAX_RETRIES  2
  SEEKPEEK_SEARCH_QPS   5
  SEEKPEEK_FETCH_QPS    5

• Probing https://api.deepseek.com/v1/tools/search …
✓ Search works — 1 result billed. Top hit: …

CLI

uvx seekpeek                                  # stdio MCP server (what hosts launch)
uvx seekpeek --transport streamable-http      # HTTP MCP server on 127.0.0.1:8765/mcp
uvx seekpeek doctor [--offline]               # verify key, endpoint and limits
uvx seekpeek search "DeepSeek V4 site:github.com" --count 5 --content
uvx seekpeek search "latest MCP news" --json | jq '.results[].url'
uvx seekpeek fetch https://api-docs.deepseek.com/zh-cn/guides/search
uvx seekpeek fetch example.com/docs api-docs.deepseek.com   # several URLs at once

Cost & limits

Search and Fetch are billed per successful request (¥5 per 1,000 requests at the time of writing) — count and need_content do not change the price. Failed calls, empty result sets and timeouts are free. Both endpoints allow 5 QPS per account, which seekpeek mirrors client-side.

See the official guide for the current numbers.

Development

git clone https://github.com/penn0312/seekpeek && cd seekpeek
uv sync                        # install runtime + dev dependencies
cp .env.example .env           # add your key
uv run seekpeek doctor
uv run pytest -q               # 80 tests: unit, wire-protocol and stdio end-to-end
uv run ruff check . && uv run ruff format --check .

The test suite spins up a mock DeepSeek endpoint and drives the real server over stdio, so it needs no network and no key. A live smoke test is available on request:

SEEKPEEK_E2E_LIVE=1 uv run pytest -k live   # spends one search request

Layout:

src/seekpeek/
├── cli.py         # argparse entry point: server, doctor, search, fetch
├── client.py      # DeepSeek HTTP client: auth, rate limiting, retries, URL handling
├── config.py      # environment-driven Settings
├── errors.py      # error types + the human/model-readable `describe()`
├── formatting.py  # Markdown / JSON renderers (pure functions)
├── models.py      # pydantic response models, FetchOutcome
└── server.py      # MCPServer: tools, prompt, resource, instructions

Pull requests are welcome — especially new hosts' config snippets, extra search-syntax examples, and translations of the README.

Disclaimer

seekpeek is an independent project and is not affiliated with DeepSeek. It reads public pages through the DeepSeek API, so what you point it at is subject to DeepSeek's terms and to the target site's policies.

License

MIT

Available Tools

3 tools
fetchFetch a pageA
Read-only

Fetch one web page (DeepSeek Fetch API) and return its title plus the full text as Markdown.

Use it on a url returned by search when the summary is not enough, or on any URL the user provides. Returns an explanatory error when the page is unreachable, blocked, or has no extractable content.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesAbsolute http(s) URL. A bare host such as `example.com/post` is accepted too.
max_charsNoCap on returned characters. 0 disables the cap.
response_formatNo`markdown` for reading, `json` for tooling.markdown

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=true, idempotentHint=false). The description adds value beyond them by disclosing the failure surface: an explanatory error when the page is unreachable, blocked, or has no extractable content, and the shape of a successful return.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, followed by usage and return/error behavior in three short paragraphs with no filler. Slightly more line-broken than needed, but every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only fetch tool with no output schema, the description covers return shape, error behavior, and usage context. It is nearly complete; only a note on truncation interaction with max_chars would close the remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters are already documented, including url normalization and max_chars=0 semantics. The description adds nothing about max_chars or response_format, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Fetch one web page') and names the exact return payload ('title plus the full text as Markdown') and the backing API. The word 'one' implicitly separates it from the sibling fetch_many.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete trigger ('use it on a url returned by search when the summary is not enough, or on any URL the user provides'), which is clear when-to-use context tied to the search sibling. It never states when NOT to use it or explicitly contrasts with fetch_many, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fetch_manyFetch several pagesA
Read-only

Fetch up to 10 web pages in one call and return each as Markdown.

Fetches run concurrently under the account rate limit, and one failing URL never fails the call — the error is reported in place. Prefer this over several fetch calls when you already know which URLs you need (for example the top three results of a search).

ParametersJSON Schema
NameRequiredDescriptionDefault
urlsYes1-10 absolute http(s) URLs (bare hosts are accepted).
max_charsNoPer-page cap on returned characters. 0 disables the cap.
response_formatNo`markdown` for reading, `json` for tooling.markdown

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnly/openWorld/non-idempotent), it discloses concurrency behavior, that fetches run 'under the account rate limit', and critically that a single failing URL does not fail the call but is 'reported in place'. That partial-failure contract materially changes how an agent should interpret results and cannot be inferred from the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core capability and size limits, followed by the failure/rate-limit contract and routing advice, with no filler. The second paragraph opens with a sentence fragment and an awkward mid-sentence line break, which slightly hurts readability but not substance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description covers the return shape (Markdown per page), the failure semantics, batch bounds and when to choose it over siblings. For a simple 3-parameter read-only tool, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents `urls` (1-10 absolute URLs, bare hosts accepted), `max_chars` (0 disables cap) and `response_format`. The description only restates the batch cap and Markdown default, adding no syntax or semantics beyond the structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Fetch up to 10 web pages in one call and return each as Markdown'), including the hard batch limit and output format. It is clearly distinguishable from the sibling `fetch` (single) and `search` (discovery) tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to 'prefer this over several `fetch` calls when you already know which URLs you need', naming the alternative and the selecting condition. The parenthetical example (top three search results) makes the intended `search` -> `fetch_many` workflow concrete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv0.1.0
    • First observedfetch
    • First observedfetch_many
    • First observedsearch
Deploy Server
Give agents eyes on the webHosted screenshot MCP. Send a URL, get a pixel-perfect image. $0.002 per grab. Works with Claude, Cursor, and Codex.grabbit.liveAd

TDQS

A4.4/5.0

Scored across 3 tools

Disambiguation5/5

search (discovery), fetch (single page), and fetch_many (batch page) target clearly separable operations. The only potential overlap—fetch vs fetch_many—is explicitly resolved in the description, which tells the agent to prefer fetch_many when URLs are already known. No realistic misselection risk.

Naming Consistency5/5

All names are lowercase snake_case verbs, and fetch_many follows the same verb as fetch with a transparent bulk suffix. The pattern is fully predictable across the set.

Tool Count5/5

Three tools is well-scoped for a web search-and-retrieve server: one discovery tool, one single-item retrieval, one batch retrieval. Each tool earns its place with no redundancy or filler.

Completeness4/5

search + fetch + fetch_many covers the core retrieval lifecycle, including batch retrieval, error handling per URL, and rich result metadata. Minor gaps remain, such as no documented pagination/offset for search or structured extraction beyond Markdown.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • research

    jbiscella
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to perform web research over MCP: search with a real browser, fetch JS-rendered pages, download PDFs and convert them to Markdown, then search and page through large documents using bounded previews so the context window isn't flooded.
    BSD Zero Clause

  • Fetchkeep

    rayorole
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI agents to fetch web pages, extract clean Markdown, save and search versions offline, crawl sites within bounds, and retrieve stable citations through MCP tools.
    15 npm
    Apache 2.0