zhihu MCP Server
Provides tools for interacting with Zhihu, including scraping webpages, fetching hot questions, publishing answers, and authenticating via QR code.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@zhihu MCP ServerWhat are the hot questions on Zhihu today?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Puppeteer MCP Server
This Model Context Protocol (MCP) server provides a tool for scraping webpages and converting them to markdown format using Puppeteer, Readability, and Turndown. It features a simple, rule-based interaction mechanism to handle common elements like cookie banners.
Now easily runnable via npx!
Features
Scrapes webpages using Puppeteer with stealth mode
Uses a rule-based system to automatically handle common pop-ups (e.g., cookie consent banners).
Extracts main content with Mozilla's Readability
Converts HTML to well-formatted Markdown
Handles authentication via a QR code login flow, automatically persisting sessions.
Accessible via the Model Context Protocol
Option to view browser interaction in real-time by disabling headless mode
Easily consumable as an
npxpackage.
Related MCP server: XHS MCP
Quick Start with NPX
The recommended way to use this server is via npx, which ensures you're running the latest version without needing to clone or manually install.
Prerequisites: Ensure you have Node.js and npm installed.
Environment Setup (Optional): You can configure the server using a
.envfile or shell environment variables.Example
.envfile or shell exports:# Optional (defaults shown) # TRANSPORT_TYPE=stdio # Options: stdio, sse, http # PORT=3001 # Only used in sse/http modes # DISABLE_HEADLESS=true # Uncomment to see the browser in actionRun the Server: Open your terminal and run:
npx -y zhihu-mcp-serverThe
-yflag automatically confirms any prompts fromnpx.This command will download (if not already cached) and execute the server.
By default, it starts in
stdiomode. SetTRANSPORT_TYPE=sseorTRANSPORT_TYPE=httpfor HTTP server modes.
Authentication
For tools that require you to be logged in (like publish-answer), this server uses a cookie-based authentication flow. You no longer need to provide a COOKIE environment variable.
The process is as follows:
Login: Call the
login-with-qrcodetool. This will return a QR code.Scan: Scan the QR code with the appropriate mobile app (e.g., Zhihu) to log in.
Session Saved: Once you log in, the server automatically saves the session cookies to a local file (
qrcodes/cookies.json).Automatic Authentication: All subsequent requests from tools like
scrape-webpage,get-hot-question, andpublish-answerwill automatically use these saved cookies to authenticate your session.
This means you only need to log in once, and your session will be reused until the cookies expire.
Using as an MCP Tool with NPX
This server is designed to be integrated as a tool within an MCP-compatible LLM orchestrator. Here's an example configuration snippet:
{
"mcpServers": {
"web-scraper": {
"command": "npx",
"args": ["-y", "zhihu-mcp-server"],
"env": {
// Optional:
// "TRANSPORT_TYPE": "stdio", // or "sse" or "http"
// "DISABLE_HEADLESS": "true" // To see the browser during operations
}
}
// ... other MCP servers
}
}When configured this way, the MCP orchestrator will manage the lifecycle of the zhihu-mcp-server process.
Environment Configuration Details
Regardless of how you run the server (NPX or local development), it uses the following environment variables:
TRANSPORT_TYPE: (Optional) The transport protocol to use.Options:
stdio(default),sse,httpstdio: Direct process communication (recommended for most use cases)sse: Server-Sent Events over HTTP (legacy mode)http: Streamable HTTP transport with session management
PORT: (Optional) The port for the HTTP server in SSE or HTTP mode.Default:
3001.
DISABLE_HEADLESS: (Optional) Set totrueto run the browser in visible mode.Default:
false(browser runs in headless mode).
Communication Modes
The server supports three communication modes:
stdio (Default): Communicates via standard input/output.
Perfect for direct integration with LLM tools that manage processes.
Ideal for command-line usage and scripting.
No HTTP server is started. This is the default mode.
SSE mode: Communicates via Server-Sent Events over HTTP.
Enable by setting
TRANSPORT_TYPE=ssein your environment.Starts an HTTP server on the specified
PORT(default: 3001).Use when you need to connect to the tool over a network.
Connect to:
http://localhost:3001/sse
HTTP mode: Communicates via Streamable HTTP transport with session management.
Enable by setting
TRANSPORT_TYPE=httpin your environment.Starts an HTTP server on the specified
PORT(default: 3001).Supports full session management and resumable connections.
Connect to:
http://localhost:3001/mcp
Tool Usage (MCP Invocation)
The server provides the following tools:
scrape-webpage
Scrapes a webpage and returns its content as markdown.
Tool Parameters:
url(string, required): The URL of the webpage to scrape.autoInteract(boolean, optional, default: true): Whether to automatically handle interactive elements.
get-hot-question
Gets a hot question from the specified URL.
Tool Parameters:
type(string, optional, default:day): The type of hot question list to get. Can behour,day, orweek.
publish-answer
Publishes an answer to a question on the specified URL.
Tool Parameters:
url(string, required): The URL of the question to answer.answer(string, required): The answer to publish.
login-with-qrcode
Gets a login QR code from the specified URL.
Tool Parameters:
qrSelector(string, optional): The CSS selector for the QR code element. Defaults to.Qrcode-qrcode.switchQrSelector(string, optional): The CSS selector for the button to switch to QR code login.
Response Format:''
The tool returns its result in a structured format:
content: An array containing a single text object with the raw markdown of the scraped webpage.metadata: Contains additional information:message: Status message.success: Boolean indicating success.contentSize: Size of the content in characters (on success).
Example Success Response:
{
"content": [
{
"type": "text",
"text": "# Page Title\n\nThis is the content..."
}
],
"metadata": {
"message": "Scraping successful",
"success": true,
"contentSize": 8734
}
}Example Error Response:
{
"content": [
{
"type": "text",
"text": ""
}
],
"metadata": {
"message": "Error scraping webpage: Failed to load the URL",
"success": false
}
}How It Works
Simple Interaction
The system uses a simple rule-based approach to handle common website interruptions. It searches for buttons containing keywords like "Accept", "Agree", or "Continue" and clicks them to dismiss pop-ups like cookie banners.
Content Extraction
After interactions, Mozilla's Readability extracts the main content, which is then sanitized and converted to Markdown using Turndown with custom rules for code blocks and tables.
Docker
This project includes a Dockerfile to build and run the server in a containerized environment.
Building the Docker Image
From the project root directory, run:
docker build -t zhihu-mcp-server:latest .Running the Docker Container
To run the server inside a Docker container, use the following command. You can pass environment variables using the -e flag.
To get the login QR code and persist the session, you need to mount a volume to the container. This ensures the qrcodes/cookies.json file is saved on your host machine.
// 临时调试,交互式运行
mkdir -p ./qrcodes && sudo chown 999:999 ./qrcodes && \
docker run -it --rm \
--user 999:999 \
-e TRANSPORT_TYPE=http \
-e PORT=3001 \
-v $(pwd)/qrcodes:/home/pptruser/qrcodes \
-p 3001:3001 \
zhihu-mcp-server:latest
//
mkdir -p ./qrcodes && sudo chown 999:999 ./qrcodes && \
docker run -d \
--user 999:999 \
-e TRANSPORT_TYPE=http \
-e PORT=3001 \
-p 3001:3001 \
zhihu-mcp-server:latestDocker Environment Variables
When running the server in a Docker container, you can configure it with the following environment variables:
TRANSPORT_TYPE: (Optional) The transport protocol to use.Options:
stdio(default),sse,http.Example:
-e TRANSPORT_TYPE=http
PORT: (Optional) The port for the HTTP server insseorhttpmode. You must also map this port using the-pflag in thedocker runcommand.Default:
3001.Example:
-e PORT=8080 -p 8080:8080
DISABLE_HEADLESS: (Optional) Set totrueto run the browser in visible mode. Note: This is primarily for debugging and may require additional X11 forwarding configuration to work correctly with Docker.Default:
false(browser runs in headless mode).Example:
-e DISABLE_HEADLESS=true
Installation & Development (for Modifying the Code)
If you wish to contribute, modify the server, or run a local development version:
Clone the Repository:
git clone https://github.com/morrain/zhihuMcpServer.git cd zhihuMcpServerInstall Dependencies:
npm installBuild the Project:
npm run buildRun for Development:
npm startOr, for automatic rebuilding on changes:
npm run dev
Customization (for Developers)
You can modify the behavior of the scraper by editing:
src/ai/page-interactions.ts: Add new keywords or logic for handling different types of pop-ups.src/scrapers/webpage-scraper.ts(visitWebPagefunction): Change Puppeteer options.src/utils/markdown-formatters.ts: Adjust Turndown rules for Markdown conversion.
Dependencies
Key dependencies include:
@modelcontextprotocol/sdkpuppeteer,puppeteer-extra@mozilla/readability,jsdomturndown,sanitize-htmlexpress(for SSE/HTTP modes)zod
Available Tools
6 toolsget-hot-questionB
获取热点问题,可以获取小时榜、日榜、周榜。
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | 获取热点问题榜单的类型,如 'hour', 'day', or 'week' | day |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It states the tool retrieves data, but does not explicitly confirm it is read-only, mention any side effects, authorization requirements, or rate limits. For a data retrieval tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the key purpose. However, it could be slightly expanded with additional useful information without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (1 parameter, no output schema, no annotations), the description is adequate but not complete. It explains the resource and parameter options, but does not describe the output format or the meaning of 'hot questions', which would be helpful for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a description for the 'type' parameter with enum values and default. The tool description does not add any additional meaning beyond what the schema offers, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets hot questions and specifies the available timeframes (hour, day, week). It uses a specific verb (get) and resource (hot questions), and is easily distinguishable from sibling tools which deal with authentication, scraping, and publishing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving hot questions from different time periods, but provides no explicit guidance on when to use this tool versus alternatives, nor any conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get-login-statusA
获取登录状态,登陆完成返回1,没有登陆完成返回0
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the behavioral trait: it returns 1 or 0 depending on login status. This is adequate for a simple read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys all necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, no output schema), the description is fully complete: it states the action and the expected return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and the baseline for 0 parameters is 4. The description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (获取) and resource (登录状态), and specifies the return values (1 for logged in, 0 for not logged in). It is distinct from sibling tools like login-with-qrcode and logout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking login status but provides no explicit guidance on when to use it versus alternatives, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
login-with-qrcodeC
访问知乎登陆页面,并获取二维码。
| Name | Required | Description | Default |
|---|---|---|---|
| qrSelector | No | 用于提取二维码的HTML选择器,默认值:.Qrcode-qrcode。 | |
| switchQrSelector | No | 切换成二维码登录方式对应的HTML选择器,默认为空。不为空时会操作点击切换成二维码登录方式。 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It mentions accessing a page and getting a QR code but omits crucial details like whether this involves opening a browser, if user interaction (scanning) is required, or any network effects. The behavior is underspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. However, it is in Chinese, which may be a barrier for non-Chinese agents. The brevity is appreciated, but a bit more structure (e.g., two sentences) could improve clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description is insufficient. It does not specify what the tool returns (e.g., QR code image data, URL) or any side effects (e.g., session cookies). For a login tool, more context is needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the tool description does not add extra value beyond the parameter descriptions. The baseline score of 3 is appropriate as the schema already documents both parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it accesses the Zhihu login page and retrieves the QR code. This is a specific action that distinguishes it from sibling tools like get-login-status or scrape-webpage. However, it does not explicitly clarify the output format (image, URL, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. Since there are no other login-related siblings, the context is implied but not explicit. The description lacks any conditions, prerequisites, or scenarios for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
logoutA
退出登录,清理掉本地的cookie信息。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that it cleans local cookie information, implying removal of session data. However, it does not specify if a server call is made or just client-side cleanup, which would enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, no output schema), the description is adequate. It conveys the core action and effect without missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so no additional meaning is needed. Schema coverage is 100% (none), and baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (logout) and what it accomplishes (cleaning local cookies). It distinguishes from sibling tools like login-with-qrcode and get-login-status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, but the context is straightforward: use when needing to log out. No exclusions or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
publish-answerD
发布回答, publish answer
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | 发布回答对应的页面地址。 | |
| answer | Yes | 回答的内容。 | |
| isAi | No | 是否为AI生成的内容,默认为true。如果为true,则会自动选择创作声明。 | |
| fastType | No | 是否使用快速输入模式。默认为true。 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden of disclosing behavioral traits. It does not mention side effects (e.g., posting or modifying content), authentication requirements, or rate limits. The schema hints at auto-selection for AI-generated content, but the description itself provides no behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (two words in each language), but this is under-specification rather than conciseness. It fails to include essential information, and the brevity comes at the cost of clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a mutation tool with 4 parameters, no output schema, and no annotations, the description is completely inadequate. It does not explain the workflow, return behavior, or preconditions, leaving the agent with no contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a description. The tool description adds no meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description '发布回答, publish answer' is a tautology that merely restates the tool's name in Chinese and English. It does not specify what publishing an answer entails, what resource it operates on, or how it differs from sibling tools like 'get-hot-question' or 'scrape-webpage'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not mention that the user must be logged in or that the 'url' should correspond to a question page. The sibling tools include login-related tools, but the description gives no hint of prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
scrape-webpageB
访问页面,提取页面内容并转化为 markdown 格式。
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | 要提取页面的URL。 | |
| autoInteract | No | 是否自动自动点击页面加载时的弹框,譬如cookie设置弹框等。 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so description carries full burden. It omits behavioral details like rate limits, dynamic content handling, or potential errors. The autoInteract parameter is mentioned only in schema, not in description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Front-loaded with action and output format. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description should detail return format. It mentions markdown but not structure (e.g., full HTML conversion or text only). Lacks info on error handling or pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so description adds minimal value. The 'autoInteract' parameter is explained in schema, and description does not elaborate further. Baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (access and extract), resource (page content), and output format (markdown). It distinguishes from sibling tools which handle login and publishing, making the purpose specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. While siblings are unrelated, the description lacks context on prerequisites (e.g., page accessibility) or when to avoid scraping.
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.
6 tool updates
v0.2.0- First observed
get-hot-question - First observed
get-login-status - First observed
login-with-qrcode - First observed
logout - First observed
publish-answer - First observed
scrape-webpage
TDQS
Scored across 6 tools
Each tool has a distinct purpose: retrieving hot questions, checking login status, logging in with QR code, logging out, publishing answers, and scraping webpages. No ambiguity between tools.
Naming is inconsistent: some use 'get-' prefix, others are verb-object (publish-answer), and 'logout' is a single verb. No uniform convention like 'verb_noun' across all tools.
6 tools is a reasonable count for a Zhihu MCP server covering authentication and basic content operations. It feels well-scoped without being too sparse or overwhelming.
The toolset covers authentication and basic posting but lacks critical operations like searching, viewing question/answer details, editing or deleting answers, and user profile management. Significant gaps for a comprehensive Zhihu agent.
Maintenance
Related MCP Connectors
Zhihu public hot-list, content, creator, comment, and reply tools.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Track Bilibili creators and get the latest updates on videos, dynamics, and articles. Fetch user p…
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA simple HTTP API server that allows users to publish articles, create answers, manage columns, and upload images on Zhihu (a Chinese Q&A platform) through straightforward REST API endpoints.8-
- AlicenseNot gradedqualityFmaintenanceEnables interaction with Xiaohongshu (Little Red Book) platform through automated browser operations. Supports authentication, content publishing, search, discovery, and commenting using Puppeteer-based automation.167 npm55MIT
- AlicenseNot gradedqualityDmaintenanceEnables interaction with the Boss直聘 recruitment platform to search for jobs and send automated greetings to recruiters. It features automatic QR code login and security verification using Playwright for seamless session management.MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to directly operate Zhihu, including login, publishing articles and videos, searching content, getting recommendations, and commenting.6-