如何以 stdio 方式自托管 SurfSense MCP Server 并指向自建后端【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense如果你部署了自己的 SurfSense 后端并希望让 Cursor、Claude Code、Claude Desktop 等 MCP 客户端直接操作这个后端抓取 Reddit、YouTube、Google Search 等数据、读写知识库而不是使用官方托管地址https://mcp.surfsense.com/mcp就需要以 stdio 方式自托管 MCP Server。SurfSense 的 MCP Server 只通过 REST API 与后端通信不导入任何后端代码因此它可以指向云端或自建后端stdio 模式下客户端会按需启动进程会话结束即退出不需要管理守护进程——唯一的要求是你的 SurfSense 后端在运行。本文对应仓库中的 MCP Server 文档 与 surfsense_mcp 模块说明。准备条件三样东西缺一不可正在运行的 SurfSense 后端。SURFSENSE_BASE_URL的默认值是http://localhost:8000自建后端放在哪里就把这个地址改成哪里指向 SurfSense Cloud 时则是https://api.surfsense.com。一个 SurfSense API key。在 SurfSense 工作区侧边栏打开API Playground → API Keys先为工作区打开API key access开关再创建一个 personal API key形如ss_pat_…并复制——该 key 只显示一次。uv。安装一次即可MCP Server 用它管理依赖并启动进程。安装依赖并做离线自检从 SurfSense 仓库根目录进入surfsense_mcpcd surfsense_mcp uv sync然后运行自检命令uv run python -m mcp_server.selfcheck自检脚本不需要后端、不需要网络只组装服务并检查所有工具的名称、描述和输入 schema 是否完整注册。它通过时打印selfcheck OK失败时会列出缺失或格式错误的工具并以非零码退出。这一步排除了服务进程本身起不来这类问题之后如果再失败基本可以聚焦到环境配置上。通过环境变量指向自建后端stdio 模式下所有配置都由客户端以环境变量形式传入参考 surfsense_mcp/.env.example解析逻辑见 配置模块变量必填默认值用途SURFSENSE_API_KEY是—API Playground → API Keys中创建的 keySURFSENSE_BASE_URL否http://localhost:8000要连接的后端地址自建后端改成实际运行地址SURFSENSE_WORKSPACE否—默认工作区按名称或 id省去每次会话的选型步骤SURFSENSE_TIMEOUT否180请求超时秒注意 入口文件中的强制检查stdio 传输下如果缺少SURFSENSE_API_KEY进程会直接报错退出不会带着空 key 启动。日志走 stderrstdout 保留给协议通道。在 MCP 客户端中注册所有客户端启动的是同一条命令——uv run --directory 路径 python -m mcp_server——再附带两个环境变量。命令中的/path/to/SurfSense/surfsense_mcp需要替换为你本地仓库中surfsense_mcp目录的绝对路径ss_pat_your_key_here替换为你创建的实际 key。主路径CursorCursor、Claude Desktop 等使用mcpServers结构的客户端通用写入~/.cursor/mcp.json全局配置key 不会进仓库或项目下的.cursor/mcp.json{ mcpServers: { surfsense: { command: uv, args: [run, --directory, /path/to/SurfSense/surfsense_mcp, python, -m, mcp_server], env: { SURFSENSE_BASE_URL: http://localhost:8000, SURFSENSE_API_KEY: ss_pat_your_key_here } } } }Claude Desktop 的配置方式相同通过Settings → Developer → Edit Config打开claude_desktop_config.json加入同样的mcpServers块后重启应用。可选Claude Code终端命令方式claude mcp add surfsense \ -e SURFSENSE_BASE_URLhttp://localhost:8000 \ -e SURFSENSE_API_KEYss_pat_your_key_here \ -- uv run --directory /path/to/SurfSense/surfsense_mcp python -m mcp_server加--scope project可以把服务写入.mcp.json供项目共享但文档提醒共享时不要把 key 一并提交。其他客户端的配置格式差异在 MCP Server 文档中有逐一列出值得留意OpenCode 的根键是mcp而不是mcpServers命令是单个数组环境变量放在environment下VS Code 使用servers键并显式声明type: stdioCodex 则用~/.codex/config.toml中的[mcp_servers.surfsense]段并可用codex mcp list验证。验证连接是否打通分两层检查客户端层。启动客户端后确认surfsense服务已加载Claude Code 和 Gemini CLI 在会话中运行/mcp服务应显示为 connectedCursor 打开Settings → MCP刷新服务应出现并带绿点工具列表展开VS Code 打开 Copilot Chat 的 agent 模式点工具图标确认服务已加载。端到端层。开一个新的 agent 会话直接问list my SurfSense workspaces这会调用surfsense_list_workspaces是文档给出的对 key、后端、服务三者的最小完整检查。能返回你的工作区列表说明 MCP Server 已经成功读到了自建后端。之后可以进一步跑真实任务例如让 agent 抓取讨论某个话题的 subreddit 并把摘要笔记存进工作区。出问题时按文档逐项排查文档给出了四个明确对应关系401 错误API key 错误或已过期重新创建一个。403 错误工作区没有开启 API 访问到API Playground → API Keys打开API key access开关。Could not reach SurfSense后端没在运行或SURFSENSE_BASE_URL写错——这是指向自建后端时最常见的一种先确认后端进程活着、地址端口正确。服务进程无法启动在surfsense_mcp目录内跑uv run python -m mcp_server.selfcheck它可以在不依赖后端的情况下验证全部工具是否正常注册。边界与限制stdio 模式下客户端按会话拉起进程、随会话结束关闭没有需要长期驻留的进程要维护只有你的 SurfSense 后端必须保持在线。计费方式与 REST API 完全一致scraper 工具按返回条目计量每次调用都会记录在API Playground → Runs。关于工具数量文档不同位置给出的数字不一致正文开头写 28 个、排错与 Cursor 段落写 25 个以你客户端中实际加载出的工具列表为准完整清单可参考 surfsense_mcp/README.md 和上述文档的工具表。【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何以 stdio 方式自托管 SurfSense MCP Server 并指向自建后端？
如何以 stdio 方式自托管 SurfSense MCP Server 并指向自建后端【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense如果你部署了自己的 SurfSense 后端并希望让 Cursor、Claude Code、Claude Desktop 等 MCP 客户端直接操作这个后端抓取 Reddit、YouTube、Google Search 等数据、读写知识库而不是使用官方托管地址https://mcp.surfsense.com/mcp就需要以 stdio 方式自托管 MCP Server。SurfSense 的 MCP Server 只通过 REST API 与后端通信不导入任何后端代码因此它可以指向云端或自建后端stdio 模式下客户端会按需启动进程会话结束即退出不需要管理守护进程——唯一的要求是你的 SurfSense 后端在运行。本文对应仓库中的 MCP Server 文档 与 surfsense_mcp 模块说明。准备条件三样东西缺一不可正在运行的 SurfSense 后端。SURFSENSE_BASE_URL的默认值是http://localhost:8000自建后端放在哪里就把这个地址改成哪里指向 SurfSense Cloud 时则是https://api.surfsense.com。一个 SurfSense API key。在 SurfSense 工作区侧边栏打开API Playground → API Keys先为工作区打开API key access开关再创建一个 personal API key形如ss_pat_…并复制——该 key 只显示一次。uv。安装一次即可MCP Server 用它管理依赖并启动进程。安装依赖并做离线自检从 SurfSense 仓库根目录进入surfsense_mcpcd surfsense_mcp uv sync然后运行自检命令uv run python -m mcp_server.selfcheck自检脚本不需要后端、不需要网络只组装服务并检查所有工具的名称、描述和输入 schema 是否完整注册。它通过时打印selfcheck OK失败时会列出缺失或格式错误的工具并以非零码退出。这一步排除了服务进程本身起不来这类问题之后如果再失败基本可以聚焦到环境配置上。通过环境变量指向自建后端stdio 模式下所有配置都由客户端以环境变量形式传入参考 surfsense_mcp/.env.example解析逻辑见 配置模块变量必填默认值用途SURFSENSE_API_KEY是—API Playground → API Keys中创建的 keySURFSENSE_BASE_URL否http://localhost:8000要连接的后端地址自建后端改成实际运行地址SURFSENSE_WORKSPACE否—默认工作区按名称或 id省去每次会话的选型步骤SURFSENSE_TIMEOUT否180请求超时秒注意 入口文件中的强制检查stdio 传输下如果缺少SURFSENSE_API_KEY进程会直接报错退出不会带着空 key 启动。日志走 stderrstdout 保留给协议通道。在 MCP 客户端中注册所有客户端启动的是同一条命令——uv run --directory 路径 python -m mcp_server——再附带两个环境变量。命令中的/path/to/SurfSense/surfsense_mcp需要替换为你本地仓库中surfsense_mcp目录的绝对路径ss_pat_your_key_here替换为你创建的实际 key。主路径CursorCursor、Claude Desktop 等使用mcpServers结构的客户端通用写入~/.cursor/mcp.json全局配置key 不会进仓库或项目下的.cursor/mcp.json{ mcpServers: { surfsense: { command: uv, args: [run, --directory, /path/to/SurfSense/surfsense_mcp, python, -m, mcp_server], env: { SURFSENSE_BASE_URL: http://localhost:8000, SURFSENSE_API_KEY: ss_pat_your_key_here } } } }Claude Desktop 的配置方式相同通过Settings → Developer → Edit Config打开claude_desktop_config.json加入同样的mcpServers块后重启应用。可选Claude Code终端命令方式claude mcp add surfsense \ -e SURFSENSE_BASE_URLhttp://localhost:8000 \ -e SURFSENSE_API_KEYss_pat_your_key_here \ -- uv run --directory /path/to/SurfSense/surfsense_mcp python -m mcp_server加--scope project可以把服务写入.mcp.json供项目共享但文档提醒共享时不要把 key 一并提交。其他客户端的配置格式差异在 MCP Server 文档中有逐一列出值得留意OpenCode 的根键是mcp而不是mcpServers命令是单个数组环境变量放在environment下VS Code 使用servers键并显式声明type: stdioCodex 则用~/.codex/config.toml中的[mcp_servers.surfsense]段并可用codex mcp list验证。验证连接是否打通分两层检查客户端层。启动客户端后确认surfsense服务已加载Claude Code 和 Gemini CLI 在会话中运行/mcp服务应显示为 connectedCursor 打开Settings → MCP刷新服务应出现并带绿点工具列表展开VS Code 打开 Copilot Chat 的 agent 模式点工具图标确认服务已加载。端到端层。开一个新的 agent 会话直接问list my SurfSense workspaces这会调用surfsense_list_workspaces是文档给出的对 key、后端、服务三者的最小完整检查。能返回你的工作区列表说明 MCP Server 已经成功读到了自建后端。之后可以进一步跑真实任务例如让 agent 抓取讨论某个话题的 subreddit 并把摘要笔记存进工作区。出问题时按文档逐项排查文档给出了四个明确对应关系401 错误API key 错误或已过期重新创建一个。403 错误工作区没有开启 API 访问到API Playground → API Keys打开API key access开关。Could not reach SurfSense后端没在运行或SURFSENSE_BASE_URL写错——这是指向自建后端时最常见的一种先确认后端进程活着、地址端口正确。服务进程无法启动在surfsense_mcp目录内跑uv run python -m mcp_server.selfcheck它可以在不依赖后端的情况下验证全部工具是否正常注册。边界与限制stdio 模式下客户端按会话拉起进程、随会话结束关闭没有需要长期驻留的进程要维护只有你的 SurfSense 后端必须保持在线。计费方式与 REST API 完全一致scraper 工具按返回条目计量每次调用都会记录在API Playground → Runs。关于工具数量文档不同位置给出的数字不一致正文开头写 28 个、排错与 Cursor 段落写 25 个以你客户端中实际加载出的工具列表为准完整清单可参考 surfsense_mcp/README.md 和上述文档的工具表。【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考