还在手动记账，月底对着Excel表格发呆？作为一名长期使用Beancount进行复式记账的用户，我深知命令行查询的繁琐和“坚持不下去”的痛苦。直到我遇到了 beancount-mcp，它利用MCP协议将AI助手变成了我的私人会计，现在只需对Claude说“查一下上个月餐饮支出”，数据马上自动呈现。这不仅是工具，更是个人财务管理方式的升级。项目基本信息信息项详情项目名称beancount-mcpGitHub地址https://github.com/StdioA/beancount-mcp项目描述A MCP Server for beancount query and transaction submmit.作者StdioA开源协议MIT License开源状态公开状态LanguagesPython支持平台Windows / macOS / Linux最后更新2026-02-21一、项目介绍beancount-mcp 是一个基于 Model Context Protocol（模型上下文协议）构建的服务器工具，它充当了 AI 助手与 Beancount 账本之间的桥梁[1]。简单来说，它让你可以使用自然语言，通过 AI 来查询账本中的交易记录，甚至向账本中提交新的记账条目。传统的 Beancount 使用体验高度依赖命令行：你要记住 bean-query 的语法规则，手动编写 BQL 查询语句才能从账本中提取数据。对于非技术人员来说，这个学习门槛相当高。而 beancount-mcp 的核心理念就是打破这个壁垒，让你用最直观的方式与财务数据对话。目前，该项目支持两种传输模式：标准输入输出和服务器发送事件，可以灵活适配不同类型的 MCP 客户端[3]。无论你使用的是 Claude for Desktop、LobeChat，还是其他支持 MCP 协议的 AI 工具，都能轻松接入。二、核心优势采用 MCP 协议进行交互是 beancount-mcp 的最大亮点。在过去，AI 无法直接读取你本地的账本文件，你需要频繁地复制粘贴数据。而现在，beancount-mcp 作为中间层，赋予了 AI 直接操作账本的能力1。这意味着你的财务数据始终保存在本地，无需上传到任何云端服务，在享受 AI 便利的同时，确保了数据的绝对隐私。从技术角度看，它的部署极为轻量。项目基于 Python 开发，依赖管理工具 uvx 即可一键运行，无需复杂的环境配置1。同时，MIT 开源协议意味着你可以自由使用、修改和分发代码，无论是个人使用还是企业内部集成，都没有任何授权限制。值得一提的是，社区对此类工具的关注度正在快速上升。虽然 beancount-mcp 本身是一个相对年轻的项目，但它所代表的 AI + 本地财务数据的方向，正在吸引越来越多的开发者和用户参与贡献和完善。三、适用场景如果你是 Beancount 的长期用户，厌倦了频繁敲击命令行查询账本，那么 beancount-mcp 能彻底改变你的使用习惯。你可以直接问 AI “今年我在餐饮上的总支出是多少”，或者“展示上个月收入最高的三笔交易”，AI 会自动生成对应的 BQL 查询并返回结果。如果你正在尝试构建个人 AI 助理工作流，beancount-mcp 可以作为其中的“财务数据模块”。搭配其他 MCP 服务器，你的 AI 助手可以同时管理你的日历、邮件和账本，形成一个完整的自动化管理闭环。如果你是开发者，想要为自己的开源项目增加 AI 交互能力，beancount-mcp 是一个很好的参考实现。它展示了如何封装一个命令行工具使其支持 MCP 协议，以及如何设计工具的参数和返回格式。四、安装教程在开始安装之前，请确保你的系统满足以下要求：Python 3.10 或更高版本，以及 uvx 工具（用于运行 Python 包）1。如果你还没有安装 uv，可以通过 pip 进行安装：pip install uv。第一步：准备 Beancount 账本文件你需要有一个现成的 Beancount 账本文件。如果你是从零开始，可以先创建一个简单的 .bean 文件作为测试。假设你的文件路径为 /Users/yourname/main.bean，请记住这个路径，后面会用到。第二步：配置 MCP 客户端以 Claude for Desktop 为例，你需要编辑它的配置文件。在 macOS 上，配置文件位于 ~/Library/Application Support/Claude/claude_desktop_config.json；在 Windows 上，位于 %APPDATA%\Claude\claude_desktop_config.json[6]。打开配置文件，添加以下内容：{ "mcpServers": { "beancount-mcp": { "command": "uvx", "args": [ "beancount-mcp", "--transport=stdio", "/Users/yourname/main.bean" ] } } }请务必将 /Users/yourname/main.bean 替换为你自己的账本文件的实际路径1。第三步：重启客户端保存配置文件后，完全退出并重新启动 Claude for Desktop。重启后，你会在输入框附近看到一个锤子或插件的图标，点击它应该能看到 beancount-mcp 提供的工具列表，这表示配置已生效[6]。针对 LobeChat 用户的配置如果你使用的是 LobeChat，配置方式略有不同。打开 LobeChat 桌面版，进入“设置 - 默认 Agent”，然后选择“插件设置 - 自定义插件”。点击“快速导入 JSON 配置”，将以下 JSON 粘贴进去即可完成安装1：{ "mcpServers": { "stdioa-beancount-mcp": { "args": [ "beancount-mcp", "--transport=stdio", "PATH_TO_YOUR_LEDGER" ], "command": "uvx" } } }验证安装配置完成后，你可以尝试在 AI 对话框中输入类似“帮我查一下账本里最新的5笔交易”的指令。如果 AI 能够正确调用工具并返回结果，说明安装已经成功。五、使用示例一旦安装配置完成，你就可以通过自然语言与账本进行交互了。以下是几个典型的使用场景和对应的对话示例。场景一：查询最近的交易记录你可以直接对 AI 说：“展示我账本里最近发生的10笔交易”。beancount-mcp 会执行相应的查询，AI 会将结果以清晰的列表形式呈现给你，包括交易日期、描述、金额和账户信息。场景二：按条件筛选数据复杂的条件筛选也可以一句话完成：“查询今年2月份所有金额大于100元的餐饮支出”。AI 会自动理解你的意图，调用 beancount-mcp 执行 BQL 查询，然后返回符合条件的所有交易。你不需要记住任何 BQL 语法。场景三：提交新的交易记录除了查询，你还可以通过对话向账本中添加新的交易。例如：“记录一笔今天的支出：午餐消费48元，从微信支付账户支出，分类为餐饮”。beancount-mcp 会将此交易提交到你的账本文件中。不过请注意，新提交的交易可能需要你手动审核格式，或者按照你的配置自动追加到文件末尾。场景四：数据分析与汇总你也可以进行更高层次的财务分析。“帮我统计一下这个月的总支出，并按分类从高到低排序”。AI 会通过多次调用 beancount-mcp 获取必要的数据，然后给出分析结果和可视化建议。高级提示由于 beancount-mcp 目前主要提供查询和提交两个核心功能，对于更复杂的分析需求，你可以结合 AI 的数据处理能力。比如，让 AI 先查询出一段时间的全部交易，然后要求它“按星期几统计平均消费金额，找出我花钱最多的那一天”，AI 会在本地计算结果，无需修改账本文件。六、常见问题Q: 配置完成后，AI 提示“未找到 MCP 服务器”或工具列表为空怎么办？A: 首先检查配置文件中的路径是否正确，特别是账本文件的绝对路径。其次，确认 uvx 命令是否可用，可以在终端中手动运行 uvx beancount-mcp --help 测试。最后，确保你完全退出并重启了客户端，而不仅仅是关闭窗口。Q: 我想使用 SSE 模式而不是 stdio，应该如何配置？A: 在配置文件的 args 数组中，将 --transport=stdio 替换为 --transport=sse 即可。不过请注意，不同的客户端对 SSE 模式的支持程度不同，stdio 模式是最通用和稳定的选择。Q: 服务器提示“command not found: uvx”如何解决？A: 这说明你的系统中没有安装 uv。执行 pip install uv 进行安装。安装完成后，建议重新启动终端和客户端，确保环境变量已更新。Q: 我可以在远程服务器上运行 beancount-mcp 吗？A: 理论上可以，但需要注意 MCP 协议目前主要在本地场景下使用。如果你确实需要远程访问，可以考虑通过 SSH 隧道等方式转发端口，但这会增加配置的复杂度。beancount-mcp 被标记为“本地服务”，意味着它更适合运行在客户端所在的设备上1。Q: 提交交易后，账本文件没有变化？A: 这种情况通常与权限或文件路径有关。请确保你的账本文件具有写入权限，并且配置文件中的路径是准确无误的。如果问题依旧，可以尝试提交一笔最简单的交易进行测试，例如：“记录一笔1元的测试交易”。七、总结beancount-mcp 精准地解决了 Beancount 用户的一大痛点：查询和录入的繁琐操作。通过 MCP 协议，它将强大的 AI 语言理解能力与严谨的本地复式记账系统无缝连接起来。对于已经沉浸在 Beancount 生态中的用户来说，这个项目几乎是一个必装工具，它能显著降低日常使用的摩擦感。当然，作为一个较新的项目，它仍有完善空间。目前的功能主要覆盖查询和提交，更高级的操作如账户管理、批量导入等尚未支持。另外，MCP 协议本身就是快速演进的标准，未来客户端和服务端的兼容性问题也需要留意。如果你正在寻找一种让 AI 真正融入个人财务管理的方法，beancount-mcp 是一个值得投入时间尝试的方案。它开源、免费、隐私安全，并且代表了一个明确的技术趋势。不妨花一个小时配置体验一下，你可能会重新爱上记账这件事。
1. 基本信息信息项详情文件名称ImageProcessor.php文件路径/usr/plugins/MarkdownImageLocalizer/ImageProcessor.php修改描述修复BUG最后更新2026-05-032. 修改说明（简述）本次修改修复了 MarkdownImageLocalizer 插件中远程图片重复下载的问题。当文章内容中的第一张图片被提取为封面时，由于文件名生成逻辑使用随机ID，导致同一张图片被下载两次，造成服务器存储空间浪费。3. 修改详情修改点 1：第 166-168 行，文件名生成逻辑修改前代码：// 生成文件名 $fileName = sprintf('%u', crc32(uniqid())) . '.' . $ext;修改后代码：// 生成基于内容哈希的文件名，防止重复下载相同图片 $hash = md5($imageData); $fileName = $hash . '.' . $ext;修改作用： 将文件名从基于随机ID改为基于图片内容的MD5哈希值，确保相同内容的图片生成相同的文件名，从根本上避免重复下载。修改点 2：第 182-195 行，文件保存逻辑修改前代码：// 保存文件 $uploadPath = $uploadDir . '/' . $fileName; if (!file_put_contents($uploadPath, $imageData)) { throw new \Exception('Cannot save file'); } // 压缩图片 if ($compressQuality > 0 && $compressQuality <= 100) { $this->compressImage($uploadPath, $compressQuality); }修改后代码：// 保存文件 $uploadPath = $uploadDir . '/' . $fileName; // 检查文件是否已存在，避免重复保存 if (!file_exists($uploadPath)) { if (!file_put_contents($uploadPath, $imageData)) { throw new \Exception('Cannot save file'); } // 压缩图片 if ($compressQuality > 0 && $compressQuality <= 100) { $this->compressImage($uploadPath, $compressQuality); } } else { $log = "[" . date('Y-m-d H:i:s') . "] File already exists: {$uploadPath}\n"; @file_put_contents($debugFile, $log, FILE_APPEND); }修改作用： 添加文件存在检查逻辑，当图片文件已存在时跳过保存操作，避免重复写入相同内容，并记录调试日志。4. 影响范围影响模块：仅影响 ImageProcessor 图片处理类配置变更：无需更新配置数据库：不涉及数据库变更兼容性：完全向后兼容，不影响现有功能5. 测试建议发布测试文章：创建一篇包含远程图片的文章并发布检查图片URL：查看文章页面，确认封面图片和内容中的第一张图片URL是否相同验证文件唯一性：检查服务器 /usr/uploads/YYYY/MM/ 目录，确认同一张图片只存在一个文件查看调试日志：检查 debug.log 文件，确认出现 "File already exists" 日志（表示重复检测生效）
【修复】侧边栏全局置顶文章数量不遵循插件配置
1. 基本信息信息项详情文件名称sidebar-left.php文件路径/usr/themes/default/sidebar-left.php修改描述修复BUG最后更新2026-05-022. 修改说明（简述）修复了首页左侧栏全局置顶文章数量不遵循插件配置的问题。原代码仅通过单一方式读取配置，当配置读取失败时始终使用默认值5篇。修改后增加了双重读取机制，确保正确获取插件设置的置顶数量。3. 修改详情（核心内容）修改点 1：全局置顶数量配置读取逻辑（第 7-35 行）修改前代码：$categoryStickyConfig = $options->plugin('CategorySticky'); if ($categoryStickyConfig && property_exists($categoryStickyConfig, 'global_sticky_count')) { $configValue = intval($categoryStickyConfig->global_sticky_count); if ($configValue > 0) { $globalStickyCount = $configValue; } }修改后代码：// 方法1：尝试从Widget_Options获取插件配置 $categoryStickyConfig = $options->plugin('CategorySticky'); if ($categoryStickyConfig && isset($categoryStickyConfig->global_sticky_count)) { $configValue = intval($categoryStickyConfig->global_sticky_count); if ($configValue > 0) { $globalStickyCount = $configValue; } } // 方法2：如果方法1失败，直接从数据库读取配置 if ($globalStickyCount == 5) { $pluginConfig = $db->fetchRow($db->select('value') ->from('table.options') ->where('name = ?', 'plugin:CategorySticky')); if ($pluginConfig) { $configData = Typecho_Common::jsonDecode($pluginConfig['value'], true); if (isset($configData['global_sticky_count']) && intval($configData['global_sticky_count']) > 0) { $globalStickyCount = intval($configData['global_sticky_count']); } } }修改作用：增加了配置读取的双重保障机制。当标准插件配置接口无法获取配置时，自动降级到直接从数据库读取，确保侧边栏置顶文章数量始终遵循插件后台设置。4. 影响范围影响模块：首页左侧栏（sidebar-left.php）的全局置顶文章列表展示配置更新：无需额外配置，修改后自动读取现有插件配置数据库：仅增加了一条查询，无数据变更5. 测试建议在插件后台设置「全局置顶数量」为20篇访问首页查看左侧栏置顶文章列表确认显示数量与插件配置一致（如设置20则显示20篇，若数据库中置顶文章不足则显示实际数量）
你是否正在学习如何构建一个MCP服务器，却不知道从哪里开始？或者需要一个完整但不过于复杂的项目来理解MCP的核心概念？poc-mcp-server正是这样一个理想的起点。poc-mcp-server是一个概念验证性质的MCP服务器实现。它演示了如何使用TypeScript构建一个功能完整的MCP服务器，提供了对Loomers、表单、表单响应和项目等资源的访问和操作工具。对于想要学习MCP服务器开发模式的开发者来说，这是一个极好的学习范例。项目基本信息信息项详情项目名称poc-mcp-serverGitHub地址https://github.com/BrunoSSantana/poc-mcp-server项目描述暂无描述作者BrunoSSantana开源协议MIT License开源状态公开状态LanguagesTypeScript支持平台Windows / macOS / Linux最后更新2025-03-31一、项目介绍poc-mcp-server是一个演示性质的MCP服务器，它的代码结构清晰，注释完整，非常适合作为学习MCP服务器开发的入门材料。它实现了多个典型的MCP工具，涵盖了列表获取、分页、过滤和排序等常见模式。该项目包含的工具围绕一个虚构的业务场景设计：管理Loomers（某种人员或实体）、表单、表单响应和项目。虽然数据是模拟的，但代码实现方式与实际项目高度一致。你可以在理解其架构后，轻松地将模式应用到自己的真实数据源上。服务器使用TypeScript编写，并依赖pnpm作为包管理器。它包含了完整的开发、构建、测试和代码检查流程，是一个规范的Node.js项目。二、核心优势完美的学习范例：项目的代码量适中，结构清晰。它展示了如何组织MCP服务器的代码、如何定义工具、如何处理请求参数、如何实现分页和过滤等核心功能。对于任何想学习MCP服务器开发的开发者来说，这是一个可以直接参考的模板。完整的功能演示：它不只是展示一个工具，而是演示了五种不同的工具，覆盖了列表查询和基于位置的查询等模式。每个工具都包含了可选参数的实现，展示了如何输入验证和错误处理。现代化的开发工具链：项目使用了TypeScript、pnpm、Biome（代码检查和格式化）、Vitest（测试框架）。这些工具代表了当前JavaScript/TypeScript生态中的最佳实践。学习这个项目，也能帮助你了解现代Node.js项目的配置和工具链。开箱即用的工程化配置：项目包含完整的package.json脚本（dev、build、start、test、lint），以及Docker和Smithery配置文件。你可以直接fork或克隆这个项目，作为自己MCP服务器开发的基础模板。三、适用场景场景一：学习MCP服务器开发。这是本项目最主要的用途。你可以通过阅读和运行这个项目，理解一个MCP服务器是如何构建的，包括如何设置开发环境、定义工具、处理请求等。场景二：作为新项目的脚手架。如果你准备开发一个新的MCP服务器，可以以这个项目为基础进行修改。它已经配置好了TypeScript编译、测试框架和代码检查工具，你只需要替换业务逻辑即可。场景三：面试准备和技术分享。这个概念验证项目可以作为一个很好的示例，向面试官或同事展示你对MCP协议的理解，以及你的TypeScript和工程化能力。场景四：理解MCP工具的设计模式。通过研究它实现的五种工具，你可以学习到如何处理列表查询、如何实现分页、如何支持过滤和排序，以及如何设计基于位置的查询。四、安装教程由于这是一个Node.js项目，安装非常简单。第一步：确保环境安装Node.js 18或更高版本安装pnpm包管理器（可以通过npm install -g pnpm安装）第二步：克隆并安装# 克隆项目 git clone https://github.com/BrunoSSantana/poc-mcp-server cd poc-mcp-server # 安装依赖 pnpm install # 构建项目 pnpm build # 启动服务器（用于测试） pnpm start第三步：配置MCP客户端要将其集成到Claude Desktop等MCP客户端中，需要在客户端配置文件中添加配置。以Claude Desktop为例，找到配置文件（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json，Windows: %APPDATA%\Claude\claude_desktop_config.json），添加：{ "mcpServers": { "poc-mcp-server": { "command": "node", "args": [ "/你的完整路径/poc-mcp-server/build/index.js" ] } } }注意：需要将路径替换为克隆项目后build/index.js的绝对路径。第四步：验证重启MCP客户端后，AI应该可以调用getLoomers、getProjects等工具。五、使用示例由于这个服务器使用的是模拟数据，它的主要价值在于演示模式而非实际生产数据。以下是假想的对话示例。示例一：获取Loomers列表你问：“请列出所有的Loomers。”AI会调用getLoomers工具，返回一个模拟的Loomer列表。示例二：获取特定区域的Loomers你问：“帮我找出位于某个区域的Loomers。”AI会调用getLoomersInArea工具，并传入位置参数。示例三：获取表单及其响应你问：“我有哪些表单？给最新的三份表单。”AI会调用getForms工具，并可能使用limit和sortBy参数。示例四：分页查询项目你问：“项目列表的第二页，每页显示5条。”AI会调用getProjects工具，设置page: 2和limit: 5。六、常见问题问题一：运行pnpm install时提示找不到命令。解决方案：这说明pnpm没有安装。请先运行npm install -g pnpm全局安装pnpm，然后再试。问题二：配置到Claude Desktop后，AI找不到或无法调用工具。解决方案：请确认你在配置中使用了build/index.js的绝对路径。同时检查.env.example文件，如果需要配置API端点或密钥，请复制为.env文件并填写正确的值。重启Claude Desktop前，请先确保构建成功（pnpm build）。问题三：这个服务器似乎只返回模拟数据，能接入真实数据吗？解决方案：可以。项目的核心框架是通用的，你需要修改src/tools/下的文件，将模拟数据返回替换为从你的真实数据库或API获取数据的逻辑。这也是该项目作为“概念验证”的意义——验证模式可行后，你可以替换数据源。问题四：如何添加新的工具？解决方案：在src/tools/目录下创建一个新文件，按照其他工具的格式实现工具的定义和处理逻辑，然后在src/index.ts中注册这个新工具即可。问题五：项目只支持stdio传输吗？解决方案：目前的实现主要聚焦于MCP核心功能。如果需要HTTP或SSE支持，可以参考其他MCP服务器项目进行扩展。七、总结poc-mcp-server是一个小而美的MCP服务器参考实现。它的首要价值不是提供即用的功能，而是作为一个“教学脚手架”存在。对于任何想要踏入MCP服务器开发领域的开发者来说，它是一个可以直接运行、阅读和修改的完整范例。这个项目展示了如何组织TypeScript MCP项目、如何定义和注册多个工具、如何处理分页和过滤等通用模式，以及如何使用现代工程化工具链。它的代码量（15次提交记录，完整的src目录）恰到好处——不会简单到无参考价值，也不会复杂到难以理解。如果你正计划编写自己的MCP服务器，我强烈建议你先克隆并运行poc-mcp-server。理解它的结构后，你会发现开发一个MCP服务器并没有想象中那么困难。这个小小的概念验证项目，可能是你进入MCP生态系统的第一块踏脚石。
对于坚持复式记账、使用Beancount管理个人财务的用户来说，查询账目和录入交易往往需要在命令行和文本编辑器之间来回切换。如果能让你的AI助手直接帮你执行Beancount查询，甚至根据你的指令生成并提交新的交易记录，是不是能极大地提升记账的效率和乐趣？这正是beancount-mcp所带来的改变。beancount-mcp是一个模型上下文协议服务器，它连接了强大的复式记账工具Beancount与你的AI助手。通过这个服务器，你的AI可以执行Beancount查询，读取你的账目数据，甚至可以将你口述的消费记录格式化成Beancount交易并提交到账本中。项目基本信息信息项详情项目名称beancount-mcpGitHub地址https://github.com/StdioA/beancount-mcp项目描述A MCP Server for beancount query and transaction submmit.作者StdioA开源协议MIT License开源状态公开状态LanguagesPython支持平台Windows / macOS / Linux最后更新2026-02-21一、项目介绍beancount-mcp是一个简洁而专注的MCP服务器。它的核心目标是与Beancount账本文件进行交互，提供两种主要能力：查询和提交。通过查询功能，你的AI可以读取并分析Beancount账本中的数据。例如，你可以问“我这个月餐饮支出一共多少？”或者“我的资产净值在过去三个月的变化趋势是什么？”AI会将这些自然语言问题转化为Beancount查询语句（如bean-query），执行后并将结果解释给你。通过提交功能，你可以用自然语言告诉AI一笔新的消费，比如“今天午饭花了50元，从餐饮支出账户扣，用信用卡支付的。”AI会理解这句话，将其格式化成标准的Beancount交易格式，并追加到你的账本文件中。这极大地简化了日常记账的录入过程。该服务器通过uvx命令即可运行，无需复杂的安装。它支持stdio和SSE两种传输方式，可以方便地集成到Claude Desktop等MCP客户端中。二、核心优势用自然语言查询财务数据：你不需要记忆复杂的Beancount查询语法，也不需要打开终端手动输入命令。只需要像和朋友聊天一样，问你的AI助手关于你财务状况的任何问题。服务器会负责将你的问题转化为精确的查询并执行。通过对话完成记账录入：记账最大的痛点就是录入。每一笔消费都需要按照严格的格式记录日期、账户、金额、描述。beancount-mcp允许你用“我今天买了一本书，花了68元”这样简单的句子完成录入。AI会帮你生成正确的交易格式。开源透明，完全掌控数据：所有的代码都是开源的，你的账本文件始终保留在你自己的电脑上。这意味着你的财务数据永远不会离开你的控制。轻量级，开箱即用：作为一个Python项目，它可以通过uvx直接运行，不需要克隆代码或手动安装依赖。对于熟悉Python和Beancount的用户来说，配置过程非常简单。三、适用场景场景一：日常记账录入。这是最常用的场景。每次消费后，你可以发给AI一条消息：“午餐支出45元，从餐饮预算账户扣，使用支付宝。” AI会生成对应的Beancount交易并追加到你的账本中。场景二：快速财务概览。你可以随时提问：“我这个月总支出是多少？”“我的主要消费类别是什么？”“我的信用卡账户余额还有多少？” AI会执行查询并告诉你答案。场景三：生成财务报告。你可以要求AI：“帮我查一下过去三个月的餐饮支出趋势，按月份汇总。” AI会执行相应的查询，并可以配合其他MCP工具将结果生成图表或报告。场景四：预算监控。你可以设置AI定期检查：“我这个月的餐饮预算还剩多少？” 或者当某类支出接近预算时，让AI发出提醒。四、安装教程使用beancount-mcp前，你需要有一个Beancount账本文件（通常是.bean或.beancount文件）。如果你还没有，需要先学习Beancount的基础知识并创建一个。第一步：确保环境安装Python 3.8或更高版本安装uv工具（推荐）或pip准备你的Beancount账本文件，记下它的完整路径第二步：配置MCP客户端我们以Claude Desktop为例。找到其配置文件：macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json使用文本编辑器打开该文件，添加以下配置。请务必将PATH_TO_YOUR_LEDGER替换为你的Beancount账本文件的绝对路径。{ "mcpServers": { "beancount": { "command": "uvx", "args": [ "beancount-mcp", "--transport=stdio", "PATH_TO_YOUR_LEDGER" ] } } }注意：如果你不使用uv，也可以使用python -m beancount_mcp的方式，但推荐使用uvx，它会自动处理依赖。对于Windows用户，如果直接运行遇到问题，可以尝试用cmd包装：{ "mcpServers": { "beancount": { "command": "cmd", "args": ["/c", "uvx", "beancount-mcp", "--transport=stdio", "C:\\路径\\到\\你的\\账本.bean"] } } }第三步：重启并验证保存配置文件，完全退出Claude Desktop并重新启动。现在，你可以尝试提问：“请帮我查一下我的账本里一共有多少条交易记录。”如果配置成功，AI会调用相关工具并返回结果。五、使用示例配置完成后，你就可以像和你的私人财务助理对话一样，管理你的账目了。示例一：查询总支出你问：“我这个月（2026年4月）的总支出是多少？”AI会构建一个查询，计算所有日期在2026年4月的支出交易总额。示例二：分类支出汇总你问：“帮我汇总一下过去三个月，我在‘餐饮’这个类别上的支出。”AI会执行按类别分组的查询，并返回每个月的餐饮支出金额。示例三：录入新交易你说：“记录一笔：昨天买咖啡花了28元，从我的借记卡（Assets:Checking）支付，分类到Expenses:Coffee。”AI会将这句话解析为Beancount交易格式，并追加到你的账本文件中。示例四：账户余额查询你问：“我的信用卡账户（Liabilities:CreditCard）当前余额是多少？”AI会查询信用卡账户的所有交易，计算出当前欠款金额。示例五：趋势分析你问：“过去半年，我的水电费支出有什么变化趋势？”AI会查询每个月的Utilities支出，并可以用列表或文字描述的形式返回给你。六、常见问题问题一：服务器启动后，AI提示找不到uvx命令。解决方案：这说明uv工具没有正确安装或未添加到PATH。请先运行uv --version确认。如果没有安装，请参考uv的官方文档进行安装（https://docs.astral.sh/uv/）。安装后重启终端和Claude Desktop。问题二：查询或提交时提示账本文件找不到或解析错误。解决方案：请检查你在配置文件中提供的账本文件路径是否正确，必须是绝对路径。同时，确认你的账本文件本身没有语法错误，可以尝试在终端中运行bean-check 你的账本文件来验证。问题三：提交交易时，AI生成的交易格式不正确。解决方案：Beancount的格式非常严格。如果你给出的描述不够清晰，AI可能会生成格式有误的交易。建议在提问时提供更明确的账户名称。例如，不要说“从我的饭卡扣”，而是说“从Assets:MealCard账户扣”。你可以先让AI生成交易预览，确认无误后再提交。问题四：这个服务器会修改我的原始账本文件吗？解决方案：是的，当你使用“提交交易”功能时，服务器会将新的交易追加到账本文件的末尾。建议你定期备份你的账本文件。同时，Beancount本身的设计是追加写入，不会修改历史交易，这保证了数据的安全性和可追溯性。问题五：我可以在多个客户端中同时使用这个服务器吗？解决方案：不建议这样做。因为多个客户端可能同时尝试写入同一个账本文件，会导致冲突或数据损坏。最好只在一个MCP客户端中配置和使用该服务器。如果你需要在多处访问数据，可以考虑使用SSE传输模式，并在服务端进行适当的并发控制。七、总结beancount-mcp是一个对Beancount用户来说极具实用价值的MCP服务器。它将Beancount强大但略显复杂的查询和录入操作，简化成了与AI的自然语言对话。这极大地降低了记账的操作门槛，让坚持复式记账变得更容易、更有趣。这个项目的最大魅力在于其整合性和便利性。它将一个优秀的开源复式记账工具（Beancount）与最前沿的AI交互方式（MCP）结合在了一起。对于已经或打算使用Beancount的用户来说，beancount-mcp是一个能让你的财务管理系统如虎添翼的组件。虽然项目目前的功能还比较基础（查询和提交），但它已经解决了记账流程中最核心的两个痛点。随着项目的迭代，未来可能会增加预算管理、报表生成等更高级的功能。如果你是一个追求数据自主、热爱复式记账并且乐于尝试新技术的人，我强烈推荐你尝试beancount-mcp。它可能会改变你和你的账本互动的方式。
你是否希望拥有一个完全自主可控的搜索引擎，不依赖任何商业API，并且能够绕过Cloudflare防护，爬取需要JavaScript渲染的网站？如果这一切还能与你的AI助手无缝集成，让AI帮你进行搜索，是不是听起来像一个理想的自托方案？这正是WebSearch-MCP为你带来的可能性。WebSearch-MCP是一个模型上下文协议服务器，它集成了一个自托管的网络爬虫服务，为AI助手提供真正的网络搜索能力。与其他依赖商业API（如Google、Bing）的方案不同，这个项目让你完全控制搜索过程，从爬虫到结果呈现，全部可以在你自己的基础设施上运行。项目基本信息信息项详情项目名称WebSearch-MCPGitHub地址https://github.com/mnhlt/WebSearch-MCP项目描述[Self-hosted] A Model Context Protocol (MCP) server implementation that provides a web search capability over stdio transport. This server integrates with a WebSearch Crawler API to retrieve search results.作者mnhlt开源协议ISC License开源状态公开状态LanguagesTypeScript, JavaScript支持平台Windows / macOS / Linux最后更新2026-04-27一、项目介绍WebSearch-MCP是一个架构清晰的MCP服务器。它由两部分组成：一个MCP服务器本体和一个独立的爬虫服务。MCP服务器负责与AI客户端通信，并将搜索请求转发给爬虫服务；爬虫服务则真正执行网络搜索，抓取结果并返回。爬虫服务通过Docker Compose部署，它包含两个核心容器：websearch-crawler和flaresolverr。websearch-crawler是主要的爬虫引擎，负责接收搜索请求、访问搜索引擎并解析结果。flaresolverr则是一个强大的工具，专门用于绕过Cloudflare等反爬机制，并能执行JavaScript以渲染动态网页。两者配合，使得这个爬虫能够访问很多普通爬虫无法触及的网站。该项目提供的web_search工具拥有丰富的参数。你可以指定搜索关键词、结果数量、语言、地区，还可以通过excludeDomains和includeDomains精细控制搜索的网站范围，或者通过excludeTerms过滤掉包含特定词语的结果。resultType参数还允许你限定搜索结果为新闻或博客。二、核心优势完全自托管，数据自主可控：这是该项目最核心的价值。你不需要将任何搜索查询发送给第三方API提供商（如Google、Bing、Serper）。整个搜索流程都在你自己的服务器上运行。这对于注重数据隐私、需要遵守严格数据合规性要求的组织或个人来说，是至关重要的特性。绕过Cloudflare，访问更多网站：许多搜索引擎和网站都使用Cloudflare等防护措施，这导致普通的爬虫或简单的HTTP请求无法获取内容。该项目集成的FlareSolverr服务能够模拟真实浏览器行为，成功绕过这些防护，获取其他服务可能无法访问的搜索结果。成本可控，尤其适合大规模使用：对于需要大量搜索查询的场景，使用商业API会产生不菲的费用。而自托管的爬虫服务的成本主要是运行Docker容器的服务器资源，没有按查询次数的计费。一旦你部署好服务，就可以几乎无限制地使用（受限于服务器性能和目标网站的速率限制）。丰富的过滤和定向能力：通过includeDomains和excludeDomains，你可以将搜索范围限定在特定网站（如site:github.com的替代方案），或者排除低质量的站点。excludeTerms参数能帮助你过滤掉包含特定广告或关键词的结果，获得更干净的搜索体验。三、适用场景场景一：对隐私要求极高的研究。如果你是一名记者或研究人员，不希望自己的搜索行为被任何商业公司记录和分析。通过自托管的WebSearch-MCP，你可以完全掌控所有查询日志（或不记录），实现真正的匿名搜索。场景二：大规模、自动化数据采集。如果你需要定期执行成千上万次搜索以获取市场情报或进行趋势分析，使用商业API将非常昂贵。你可以搭建一个WebSearch-MCP服务，以固定的基础设施成本承担任意数量的搜索。场景三：集成到私有AI应用。你正在构建一个私有的、内部使用的AI助手，不希望它的任何依赖是外部API。你可以将WebSearch-MCP作为这个AI的搜索后端，整个系统完全闭环运行，消除对外部服务的网络依赖和合规风险。场景四：访问反爬严格的目标网站。某些特定领域的网站或搜索引擎对爬虫非常不友好，普通方法无法获取结果。由于WebSearch-MCP使用了FlareSolverr，它能够成功访问这些受保护的站点，为你的AI提供其他工具无法获取的信息。场景五：学习搜索引擎工作原理。开发者可以通过研究这个项目，了解一个完整的“爬虫+防护绕过+搜索API+MCP集成”的现代搜索系统是如何构建的。它是一个很好的教学范例。四、安装教程WebSearch-MCP的安装分为两步：启动爬虫服务，然后配置MCP客户端。第一部分：启动爬虫服务（使用Docker Compose）前置条件：确保你的系统已安装Docker和Docker Compose。创建一个目录（例如websearch-crawler），在其中新建一个文件名为docker-compose.yml。将以下内容复制进去：version: '3.8' services: crawler: image: laituanmanh/websearch-crawler:latest container_name: websearch-api restart: unless-stopped ports: - "3001:3001" environment: - NODE_ENV=production - PORT=3001 - LOG_LEVEL=info - FLARESOLVERR_URL=http://flaresolverr:8191/v1 depends_on: - flaresolverr volumes: - crawler_storage:/app/storage flaresolverr: image: 21hsmw/flaresolverr:nodriver container_name: flaresolverr restart: unless-stopped environment: - LOG_LEVEL=info - TZ=UTC volumes: crawler_storage:对于Mac Apple Silicon用户：你需要在crawler服务中添加platform: "linux/amd64"，并在flaresolverr服务中添加platform: "linux/arm64"。完整的配置请参考项目README。在终端中，导航到docker-compose.yml文件所在的目录，运行以下命令启动服务：docker-compose up -d验证服务是否成功启动：curl http://localhost:3001/health如果返回{"status":"ok", ...}，说明爬虫服务已经准备就绪。第二部分：配置MCP客户端爬虫服务运行后，你需要配置MCP客户端（如Claude Desktop）来连接它。找到MCP客户端的配置文件，以Claude Desktop为例：macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json使用文本编辑器打开该文件，添加以下配置：{ "mcpServers": { "websearch": { "command": "npx", "args": ["websearch-mcp"], "env": { "API_URL": "http://localhost:3001", "MAX_SEARCH_RESULT": "5" } } } }API_URL需要指向你刚刚启动的爬虫服务的地址。MAX_SEARCH_RESULT是默认返回的结果数量。对于Windows用户，如果直接运行遇到问题，可以尝试用cmd包装：{ "mcpServers": { "websearch": { "command": "cmd", "args": ["/c", "npx", "websearch-mcp"], "env": { "API_URL": "http://localhost:3001", "MAX_SEARCH_RESULT": "5" } } } }第三部分：重启并验证保存配置文件，完全退出MCP客户端并重新启动。在新的对话中，尝试提问：“请帮我搜索一下‘2026年世界杯’的相关信息。”如果一切配置正确，AI会调用web_search工具，并返回从你的自托管爬虫服务中获取的搜索结果。五、使用示例配置完成后，你就可以利用完全自主可控的搜索引擎了。示例一：基础搜索你问：“搜索‘量子计算最新进展’。”AI会调用web_search工具，使用默认参数。示例二：限定域名搜索你问：“搜索‘Python async/await教程’，只来自realpython.com。”AI会设置includeDomains: ["realpython.com"]。示例三：排除特定域名和关键词你问：“搜索‘机器学习’，排除pinterest.com，同时排除标题中包含‘2020’的结果。”AI会设置excludeDomains: ["pinterest.com"]、excludeTerms: ["2020"]。示例四：搜索新闻你问：“搜索‘Apple发布会’，结果类型限定为新闻。”AI会设置resultType: "news"。示例五：多参数组合搜索你问：“搜索关于‘Rust语言2026特性’的博客文章，用英文，返回10条结果。”AI会设置query: "Rust lang 2026 features"、resultType: "blogs"、language: "en"、numResults: 10。六、常见问题问题一：首次启动后，搜索返回错误或超时。解决方案：爬虫服务（尤其是FlareSolverr）首次启动时需要下载浏览器组件，可能需要几分钟时间。你可以通过docker-compose logs crawler和docker-compose logs flaresolverr查看日志。看到类似“Browser started”或“Ready”的信息后，服务才完全就绪。问题二：搜索某些关键词时返回空结果。解决方案：这可能有几个原因。首先，检查爬虫服务是否正常运行（/health端点）。其次，某些搜索引擎（尤其是谷歌）可能会对来自数据中心IP的请求进行验证或拦截，导致返回空结果。你可以尝试在docker-compose.yml中修改爬虫使用的搜索引擎配置（如果支持）。此外，过于苛刻的速率限制也可能导致临时封禁。问题三：MAX_SEARCH_RESULT设置得太大会导致结果返回很慢。解决方案：该项目默认最大结果数建议不要设置得太大。因为每次搜索，爬虫都需要等待搜索引擎返回并解析所有结果。设置MAX_SEARCH_RESULT为5-10是比较合理的范围。如果需要更多结果，可以进行多次搜索或调整参数。问题四：爬虫服务消耗大量CPU或内存。解决方案：FlareSolverr基于浏览器引擎，确实会消耗较多的系统资源。对于Apple Silicon的Mac，注意配置正确的平台（linux/arm64）以使用原生架构，性能会更好。对于服务器部署，建议至少2GB内存。如果资源紧张，可以考虑降低FlareSolverr的实例数或调低并发。问题五：我可以在其他城市或使用代理运行爬虫服务吗？解决方案：完全可以。爬虫服务可以在任何能访问互联网的服务器上运行。你只需要将MCP客户端配置中的API_URL指向该服务器的公网IP或域名即可。这样，即使你的AI客户端在本地，搜索也会通过远端服务器进行，获得不同的搜索视角。七、总结WebSearch-MCP是一个为“控制”和“自由”而生的项目。它代表了MCP生态中一个重要的方向：自托管、去中心化、隐私优先。它不依赖任何商业搜索API，提供了完全自主的搜索解决方案。这个项目的最大亮点在于其自托管特性和强大的反爬能力。通过Docker Compose，你可以在一台服务器上快速搭建起一个生产级的、能绕过Cloudflare的爬虫集群。这对于有隐私合规要求、大规模搜索需求，或需要访问特定受限网站的场景来说，是无可替代的工具。当然，这种自由也带来了一定的运维责任。你需要管理自己的Docker容器，监控资源消耗，并解决搜索引擎可能出现的反爬挑战。但对于那些愿意为数据主权和技术自由付出这些努力的用户来说，WebSearch-MCP提供的回报是巨大的。如果你渴望完全掌控你的搜索数据，并且希望AI助手能基于一个自主、强大的搜索引擎进行信息检索，那么WebSearch-MCP值得你投入时间去探索和部署。
对于很多不想依赖谷歌生态的用户来说，必应搜索是一个绝佳的替代选择。它提供了可靠的搜索质量、丰富的API功能，并且在某些区域拥有更好的本地化结果。bing-search-mcp正是为了将这些能力无缝引入AI助手而设计的。bing-search-mcp是一个模型上下文协议服务器，它让你能够通过必应搜索API，在AI对话中执行网页、新闻和图片搜索。通过这个服务器，你的AI可以访问微软强大的搜索基础设施，获得多样化的实时信息。项目基本信息信息项详情项目名称bing-search-mcpGitHub地址https://github.com/leehanchung/bing-search-mcp项目描述MCP Server for Bing Search API作者leehanchung开源协议MIT License开源状态公开状态LanguagesPython支持平台Windows / macOS / Linux最后更新2026-04-27一、项目介绍bing-search-mcp是一个专注于必应搜索的MCP服务器。它提供了三个核心工具，覆盖了最常见的搜索需求：bing_web_search用于通用网页搜索，bing_news_search用于新闻资讯检索，bing_image_search用于图片查找。每个工具都提供了丰富的参数。你可以控制返回结果的数量、结果的偏移量（用于分页），以及指定市场区域（如“en-US”、“zh-CN”）。对于新闻搜索，你还可以通过freshness参数筛选出过去一天、一周或一个月内的最新新闻。这个服务器的设计非常轻量，并且完全基于Python实现。它使用了微软官方的必应搜索API，因此结果的稳定性和质量有商业级的保障。同时，它也内置了速率限制和错误处理机制，确保在调用API时不会因为意外错误导致AI中断。二、核心优势商业级的搜索稳定性：必应搜索API是微软的付费服务，提供了极高的可用性和稳定的响应时间。相比使用爬虫或逆向工程的免费方案，它的结果质量和服务级别协议更有保障。这对于任何对搜索可靠性有要求的应用场景都非常重要。三种搜索类型，一个服务器：你不需要为网页、新闻和图片搜索分别寻找或配置不同的MCP服务器。bing-search-mcp在一个统一的接口下集成了这三种常见的搜索需求。这不仅简化了配置，也让AI在需要混合查询时能更高效地调用。精细的区域和时效性控制：通过market参数，你可以针对特定国家或语言的用户优化搜索结果。例如，你可以让AI只搜索中文（zh-CN）内容，或者针对美国市场进行本地化搜索。freshness参数在新闻搜索中尤为有用，能帮助你找到真正的“最新”资讯。简单的配置和部署：作为MCP服务器，它可以通过uvx命令直接运行，无需克隆代码或复杂的环境设置。你只需要准备一个必应API密钥，并在客户端配置文件中添加几行JSON即可。三、适用场景场景一：多语言内容检索。当你需要搜索特定语言的内容时，可以利用market参数。“搜索‘人工智能’的中文新闻，市场设置为zh-CN。” AI能够返回更符合中文用户阅读习惯的结果。场景二：最新新闻追踪。利用bing_news_search和freshness参数，你可以轻松获取“过去24小时内关于‘台风’的新闻”。这对于舆情监控、快速资讯收集非常有帮助。场景三：视觉内容挖掘。设计师或内容创作者可以快速寻找配图。“帮我搜索‘抽象艺术’的图片，返回10张。” AI可以直接返回图片链接和描述。场景四：综合信息简报。你可以让AI同时进行网页搜索和新闻搜索。“搜索‘苹果发布会’，同时获取最新的相关新闻和通用网页结果，然后帮我整理一份简报。”场景五：低成本替代方案。对于开发环境或个人项目，必应搜索API通常提供一定额度的免费调用（例如每月1000次），这足以满足测试和轻量级使用。它是一个成本可控的、替代谷歌搜索API的方案（后者已停止向新用户开放）。四、安装教程使用bing-search-mcp前，你需要一个必应搜索API密钥。第一步：获取必应搜索API密钥访问 Microsoft Azure 门户网站。登录你的微软账户（如果没有，需要注册一个）。在搜索框中输入“Bing Search”，然后选择“Bing Search v7”资源。点击“创建”，填写必要信息（如订阅、资源组、定价层）。对于测试，可以选择免费层（F0）。创建资源后，进入资源的“密钥和终结点”页面。你会看到两个密钥（都可以用），复制其中一个。重要：必应搜索API并非完全免费，但通常注册时会提供一定额度的免费试用信用额度。请留意你的使用量。第二步：配置你的MCP客户端我们以Claude Desktop为例。找到其配置文件：macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json使用文本编辑器打开该文件，添加以下配置。请务必将your-bing-api-key替换为你的真实API密钥。{ "mcpServers": { "bing-search": { "command": "uvx", "args": ["bing-search-mcp"], "env": { "BING_API_KEY": "your-bing-api-key" } } } }如果你希望连接到特定的必应API端点（例如使用某些区域的自定义端点），可以同时设置BING_API_URL环境变量，否则它将使用微软的全球默认端点。 "env": { "BING_API_KEY": "your-bing-api-key", "BING_API_URL": "https://api.bing.microsoft.com/" }第三步：重启并验证保存配置文件，完全退出Claude Desktop并重新启动。在新的对话中，尝试提问：“请帮我搜索一下‘云计算’的相关信息，返回5条结果。”如果配置成功，AI会调用bing_web_search工具，并返回一个包含标题、链接和摘要的结果列表。五、使用示例配置完成后，你就可以在对话中灵活地使用必应搜索了。示例一：通用网页搜索你问：“搜索‘Rust language 2026 features’。”AI会调用bing_web_search，使用默认参数。示例二：新闻搜索与时效性你问：“搜索过去一周内关于‘气候变化’的新闻，给我3条。”AI会调用bing_news_search，设置freshness: "Week"，count: 3。示例三：图片搜索你问：“帮我找一些关于‘山景’的高清图片，返回5张。”AI会调用bing_image_search，设置query: "mountain view", count: 5。示例四：区域化搜索你问：“搜索‘GDP growth’，市场设置为日本（ja-JP），看看日本本地视角的结果。”AI会调用bing_web_search，设置market: "ja-JP"。示例五：分页获取更多结果你问：“搜索‘Python异步编程’，我要看第2页的结果，每页显示10条。”AI需要先理解“第2页”对应offset: 10（第一页offset为0）。然后调用bing_web_search，设置offset: 10。六、常见问题问题一：搜索时提示“API密钥无效”或“未经授权”。解决方案：请仔细检查你在配置文件中填写的BING_API_KEY是否正确，注意不要有多余的空格或引号。同时，登录Azure门户，确认你的必应搜索资源状态正常，密钥没有过期，并且你的账户有有效的付款方式或仍有免费额度。问题二：查询返回的结果数量少于count参数设定值。解决方案：这通常是因为搜索词匹配的结果总数就不足。必应API会返回它所能找到的最多结果。你可以尝试放宽搜索关键词，或者调整market参数以扩大搜索范围。问题三：我想使用必应新闻搜索的“自动”时效性，而不是指定“Day”。解决方案：根据API文档，freshness参数的默认行为是“返回所有相关结果，不考虑时效性”。如果不指定该参数，或者将其设置为null，服务器应该会按默认行为处理。你可以尝试在提问中明确告诉AI“不要限制时间范围”。问题四：这个服务器消耗的API配额大吗？解决方案：每次调用bing_search相关工具，都会消耗一次API调用。免费层通常有较低的每分钟请求数和每月总数。对于个人日常使用，少量查询一般不会超限。但对于自动化或大量查询场景，建议监控你的Azure使用情况，并考虑升级到付费层。问题五：我可以修改默认的count值（10）吗？解决方案：可以。AI可以在每次调用时通过参数传递不同的count值。如果你希望全局修改默认值，可以查看项目源码，或者为AI提供一个系统提示，指导它在未指定时使用你的首选数量。七、总结bing-search-mcp是一个简洁、专注且可靠的MCP服务器。它没有过多的花哨功能，而是扎实地实现了必应搜索API的三种核心搜索类型。它的存在，为那些倾向于微软生态、或需要谷歌API替代方案的用户，提供了一个高质量的选择。这个项目的最大优点是其专注性和易用性。它只做搜索，但做得很好。通过为网页、新闻和图片搜索提供独立的工具，它让AI能够清晰地选择最合适的方法。同时，通过uvx的安装方式，几乎实现了零配置启动。对于开发者、内容创作者，或任何需要在AI应用中集成稳定、商业级搜索能力的用户，bing-search-mcp都是一个值得信赖的工具。它或许不是功能最丰富的搜索MCP，但它是最符合简单、可靠原则的解决方案之一。如果你正在寻找一个开箱即用、稳定且由大公司支持的搜索API集成，bing-search-mcp会是你的得力助手。
kb-mcp-server是一个基于txtai的模型上下文协议服务器。它允许你将自己收集的文档、代码、笔记等构建成一个可移植的、离线的知识库，然后通过MCP协议让AI助手访问。简单来说，它能帮你为自己的AI打造一个专属的、私密的“第二大脑”。项目基本信息信息项详情项目名称kb-mcp-serverGitHub地址https://github.com/Geeksfino/kb-mcp-server项目描述Build a knowledge base into a tar.gz and give it to this MCP server, and it is ready to serve.作者Geeksfino开源协议MIT License开源状态公开状态LanguagesPython支持平台Windows / macOS / Linux最后更新2026-04-27一、项目介绍kb-mcp-server构建在txtai库之上，这是一个强大的“一站式向量数据库”，它融合了语义搜索、知识图谱构建和语言模型工作流。这个服务器提供了一整套命令行工具和MCP接口，让你可以完成从知识库构建到查询的完整流程。该项目主要包含两部分：知识库构建器（kb_builder）和MCP服务器。知识库构建器负责“喂”给AI知识。你可以将一堆文档（如PDF、Markdown、代码文件）作为输入，它会对文档进行智能分段、创建向量嵌入，并可选地构建知识图谱。最终，它可以生成一个可移植的、压缩的知识库文件（.tar.gz）。MCP服务器则负责“读取”这个知识库。当你的AI需要查询信息时，它会通过这个服务器进行语义搜索。服务器会理解问题的含义，而不仅仅是匹配关键词，从知识库中找到最相关的内容返回给AI。如果启用了知识图谱，它甚至能发现不同概念之间的隐含联系。二、核心优势完全本地化，数据永不流出：这是该项目最大的优势。所有文档预处理、向量索引和查询都在你的本地机器上完成。你不需要将数据发送给任何外部API或服务。对于处理商业机密、个人隐私或敏感研究数据来说，这是至关重要的特性。构建可移植、可分享的知识库：你能将所有知识、经验、文档打包成一个或几个文件。知识库可以像普通文件一样复制、备份，甚至分享给同事。启动服务器时，只需要指定这个文件即可，实现了知识和配置的“代码化”。语义搜索与知识图谱：它不只是做关键词匹配。当你问“如何解决内存泄漏问题”时，它能够理解你的意图，找到真正描述解决方案的段落，即使那些段落中没有“解决”这个词。此外，知识图谱功能可以揭示文档中概念之间的关系，例如找出哪些技术文档频繁引用了某个核心API。丰富的配置与优化选项：基于txtai，整个系统高度可配置。你可以选择不同的嵌入模型（如sentence-transformers）、调整分块策略、选择混合搜索权重、配置图神经网络等。通过编写YAML配置文件，你可以针对技术文档、学术论文或代码库进行精细优化，得到最佳检索效果。三、适用场景场景一：私有技术文档问答。这是最经典的应用。你可以将公司内部的所有技术文档、API说明、故障排查手册构建成一个知识库。然后让AI助手回答：“如何配置数据库连接池？”或“生产环境部署检查清单有哪些？”AI将基于你的内部文档给出准确答案，而非通用信息。场景二：个人笔记与知识库助手。如果你使用Obsidian、Logseq或Foam等工具积累了大量个人笔记，可以将整个笔记文件夹构建成知识库。之后，你可以问AI：“我关于‘微服务架构’都记了哪些要点？”或者“我之前研究过的关于Rust生命周期的文章中，最佳实践是什么？”场景三：代码库分析与文档生成。将一个开源项目或你自己的代码仓库（尤其是包含大量注释和README的）构建成知识库。你可以问AI：“这个项目的身份验证模块是如何组织的？”或者“找出所有处理用户输入的函数。”AI能帮你从代码的“知识”层面进行分析。场景四：学术文献综述辅助。与arxiv-mcp-server不同，这里你可以将本地下载的论文PDF集合构建成知识库。然后进行语义搜索：“找出讨论‘transformer模型参数量与性能关系’的段落。”这能帮你精准定位到论文中的具体论述，而不是只能读摘要。场景五：离线环境的知识支持。对于开发环境严格隔离、无法连接外网的场景，你可以先在能联网的环境中构建好知识库（比如下载的文档、论文），然后将知识库文件传输到内网，在内网的MCP服务器中加载。AI在无互联网的情况下，依然可以基于知识库提供高质量的信息。四、安装教程安装kb-mcp-server有多种方式，这里推荐使用uv和uvx，这是最干净、快捷的方式。第一步：安装uvuv是一个快速的Python包管理器。安装命令如下：macOS 或 Linux:curl -LsSf https://astral.sh/uv/install.sh | shWindows:powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"第二步：构建你的第一个知识库假设你有一个包含文档的文件夹（例如~/my_documents），里面有一些Markdown或文本文件。你可以使用uvx直接运行kb-build命令来构建知识库，无需安装任何东西。uvx --from kb-mcp-server kb-build --input ~/my_documents --export my_knowledge_base.tar.gz这个命令会处理~/my_documents下的所有文件，最终在当前目录下生成一个名为my_knowledge_base.tar.gz的知识库压缩包。你也可以用--config参数指定自定义的配置文件。第三步：配置MCP客户端以Claude Desktop为例。找到其配置文件：macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json使用文本编辑器打开该文件，添加以下配置。请将--embeddings后的路径替换为你生成的知识库文件（.tar.gz）或文件夹的绝对路径。{ "mcpServers": { "kb-server": { "command": "uvx", "args": [ "kb-mcp-server", "--embeddings", "/完整/路径/到/你的/my_knowledge_base.tar.gz" ] } } }如果你希望服务器在后台以HTTP模式运行（而非stdio），可以添加--transport sse参数。重要说明：Claude Desktop等图形化应用可能无法直接找到uvx命令。如果配置后无法连接，你需要使用虚拟环境中Python的绝对路径来运行。首先创建一个虚拟环境并安装包：uv venv source .venv/bin/activate uv pip install kb-mcp-server然后，找到你虚拟环境中的kb-mcp-server可执行文件（通常在.venv/bin/kb-mcp-server）。在配置中使用其绝对路径：{ "mcpServers": { "kb-server": { "command": "/你的项目路径/.venv/bin/kb-mcp-server", "args": ["--embeddings", "/完整/路径/到/你的/my_knowledge_base.tar.gz"] } } }第四步：重启并验证保存配置文件，完全退出Claude Desktop并重新启动。现在，你可以问一些只在你的个人文档中出现的问题了。例如：“根据我整理的笔记，我是如何定义‘知行合一’的？”如果配置成功，AI会从你的知识库中查找并回答。五、使用示例配置完成后，你的AI就能访问你的专属知识库了。以下是一些典型用法。示例一：语义搜索查询你问：“帮我查一下知识库里，关于‘函数式编程的优势’有哪些论述？”AI会调用MCP服务器的语义搜索功能，返回最相关的文档片段或段落。示例二：探索性问答你问：“根据我收集的Rust资料，所有权系统主要解决了什么问题？”AI会在你的Rust学习笔记或文档中进行语义搜索，总结出核心要点。示例三：知识图谱查询（如果构建时启用了图谱）你问：“我的知识库中，‘缓存’和‘数据库’这两个概念之间有什么联系？”AI可以从知识图谱中找出连接这两个概念的路径和相关文档。示例四：代码库理解如果你构建了一个开源项目的代码库知识库，可以问：“找出项目中所有实现了‘观察者模式’的地方。”AI会搜索代码注释、README或相关文档，定位到描述的段落。示例五：组合查询你问：“在关于‘大语言模型’的文档中，有哪些段落同时提到了‘参数高效微调’和‘LoRA’？”AI会进行精准的语义检索，返回同时包含这两个概念的片段。六、常见问题问题一：构建知识库时，如何处理PDF和Word文档？解决方案：kb_builder依赖于txtai的文件处理管道。txtai默认支持纯文本、Markdown、HTML和PDF。对于PDF，它依赖于pypdf库。对于Word文档，你需要安装docx2txt等额外依赖。最稳妥的方式是将所有文档统一转换为纯文本（.txt）或Markdown（.md）格式后再进行构建。问题二：搜索结果的准确性不高，或者返回了不相关的内容。解决方案：知识库的检索质量强烈依赖于你的文档预处理方式。有几个可以优化的方向：选择更好的嵌入模型：在配置文件中修改embeddings.path，例如使用BAAI/bge-large-en-v1.5或intfloat/e5-large-v2等高性能模型。调整分块策略（chunking）：chunk_size和chunk_overlap参数影响很大。过大会引入噪声，过小会丢失上下文。对于技术文档，通常512-1024的token大小比较合适。启用混合搜索：设置scoring: hybrid并调整hybridalpha权重（如0.75），可以平衡关键词匹配（BM25）和语义匹配。问题三：知识库文件（.tar.gz）太大，加载缓慢。解决方案：加载速度主要取决于知识库的大小和你选择的嵌入模型（模型大小会影响首次加载时间）。你可以尝试：使用更小的嵌入模型，如all-MiniLM-L6-v2。如果不需要频繁更新，可以预先将知识库文件夹准备好，而不是每次都加载tar.gz文件（解压后加载）。仅将最核心的文档构建成知识库，避免一股脑把所有资料都包含进去。问题四：构建知识库时，提示内存不足。解决方案：处理非常大的文档集（如数十GB）时，向量索引可能占用大量内存。你可以：在配置文件中降低batch大小。使用基于磁盘的向量后端，如faiss配合OnDiskInvertedIndexes，或直接使用sqlite-faiss配置。将大型文档集分批处理，构建多个知识库，再在AI层面进行路由。问题五：MCP客户端提示找不到uvx或kb-mcp-server命令。解决方案：这是macOS上图形化应用的常见问题，因为它们不加载你的shell配置文件（如.bashrc或.zshrc）。解决方法如前所述：在虚拟环境中安装包，然后在配置中使用虚拟环境中Python二进制文件的绝对路径，或者kb-mcp-server可执行文件的绝对路径。七、总结kb-mcp-server是一个将“知识库”和“AI助手”深度结合的优秀项目。它的核心价值在于私有化和可定制。借助txtai强大的能力，你可以将任何数量的本地文档，转换成一个可供AI查询的、高可用的语义搜索引擎。这个项目最大的魅力在于，它把一个非常复杂的RAG系统，包装成了一个简单、便携、开箱即用的MCP服务器。你不需要理解向量数据库的原理，不需要部署云服务，只需要运行几条命令，就能拥有一个属于自己的、可以离线运行的私有知识问答系统。对于所有拥有大量私密文档（公司知识库、个人笔记、专业文献）并且希望AI能基于这些内容提供帮助的用户，kb-mcp-server都是一个极其有价值的工具。它赋予了AI“联系上下文”的能力，但这个“上下文”是你自己构建的世界。如果你希望你的AI真正“懂”你，懂你的文档，懂你的代码，懂你的笔记，那么kb-mcp-server就是你一直在寻找的钥匙。
想象一下，你正在撰写一篇关于大语言模型的论文，需要系统性回顾过去一年arXiv上相关的前沿研究。你可能需要打开浏览器，在arXiv网站上反复搜索、筛选、下载PDF，然后手动整理笔记。这个过程耗时且繁琐。如果能让你的AI助手直接帮你搜索、下载，甚至阅读和分析论文全文，那该有多好？这正是arxiv-mcp-server为你带来的革命性体验。arxiv-mcp-server是一个模型上下文协议服务器，它为AI助手提供了完整的arXiv论文搜索、获取和分析能力。通过这个服务器，你的AI可以像一位专业的学术研究员一样，检索论文摘要、下载全文，并从海量文献中提取关键信息。项目基本信息信息项详情项目名称arxiv-mcp-serverGitHub地址https://github.com/blazickjp/arxiv-mcp-server项目描述A Model Context Protocol server for searching and analyzing arXiv papers作者blazickjp开源协议Apache License 2.0开源状态公开状态LanguagesPython支持平台Windows / macOS / Linux / Web最后更新2026-04-26一、项目介绍arxiv-mcp-server是一个功能极其丰富的MCP服务器。它提供了一套完整的工具集，覆盖了从论文发现到深度分析的整个研究生命周期。它的核心工具包括：search_papers可以按关键词、分类、日期范围搜索arXiv上的论文；download_paper能将论文以HTML或PDF格式下载到本地；read_paper可以读取已下载论文的全文（Markdown格式）；list_papers则能管理你的本地论文库。除了这些基础功能，它还提供了一系列高级分析工具。semantic_search能对你的本地论文库进行语义相似度搜索；citation_graph可以获取论文的引用和被引用关系；watch_topic和check_alerts能帮你监控特定主题的新论文发布。此外，它还内置了多个研究提示，如论文深度分析、文献综述生成等，引导AI按学术规范进行系统性的分析。这个服务器特别注重安全。它的文档中明确警告了提示词注入的风险——恶意论文内容可能试图操控AI行为。它建议用户使用只读配置并在执行AI建议前进行人工判断，显示了项目作者对实际使用场景中安全问题的深刻理解。二、核心优势完整的研究工作流支持：从搜索到下载，从阅读到分析，arxiv-mcp-server提供了一个闭环的学术研究环境。你可以先用search_papers发现相关论文，然后用download_paper保存，再用read_paper获取全文，最后利用内置的研究提示进行深度分析。整个过程不需要离开对话界面。语义搜索与引用网络分析：它的semantic_search工具能基于论文内容而非仅仅标题或摘要进行相似性搜索，帮助你发现传统关键词检索可能遗漏的相关工作。citation_graph则能让你快速了解一篇论文的学术脉络：它引用了谁，又被谁引用。这对于文献综述和追溯研究源头非常有价值。主动的研究监控功能：watch_topic和check_alerts让你能像设置新闻提醒一样监控学术领域。你可以让AI每天检查是否有关于“多智能体强化学习”的新论文发布，并在有新论文时主动通知你。这让你能始终站在研究前沿。重视安全，透明清晰：项目文档中有一整节关于提示词注入风险的说明。它诚实地指出，恶意论文内容可能试图操纵AI。它提供了具体的缓解措施，包括使用只读配置和人工审核AI建议。这种对安全问题的公开讨论在处理外部内容的AI工具中是非常可贵的。三、适用场景场景一：学术文献综述。这是最核心的应用场景。你可以让AI：“搜索过去一年arXiv上关于‘图神经网络’的论文，重点关注cs.LG和stat.ML分类，下载前10篇，然后帮我写一份文献综述，总结主要的研究趋势和未解决的问题。” AI会调用搜索、下载、阅读工具，最后利用内置的文献综述提示生成一份结构化的报告。场景二：追踪前沿动态。利用watch_topic和check_alerts，你可以让AI每周自动检查：“过去一周，‘大语言模型推理优化’这个方向有哪些新论文？帮我总结它们的核心贡献。” 这相当于拥有了一个自动化的个人研究助理。场景三：论文深度分析。当你获得一篇关键论文时，可以请求：“请对arXiv ID为2401.12345的论文进行深度分析，包括它的方法论创新点、实验设置的优缺点以及对未来研究的启示。” AI会调用deep-paper-analysis提示，按照学术规范进行系统性剖析。场景四：寻找相关研究。如果你有一篇重要的种子论文，可以问：“请找出与arXiv ID 2404.19756这篇论文最相似的5篇论文，并告诉我它们的主要研究方向。” AI会使用semantic_search工具（需要论文已下载）或在arXiv上搜索相关内容。场景五：理解研究脉络。对于不熟悉的领域，你可以问：“请帮我分析这篇论文的引用网络，它的核心思想源自哪些经典工作，又启发了哪些后续研究？” AI会使用citation_graph工具，为你绘制出一幅学术传承的图谱。四、安装教程arxiv-mcp-server提供了多种安装方式。最为推荐的是通过uv tool install，以确保可执行文件全局可用。第一步：安装uv（如果尚未安装）uv是一个快速的Python包管理器。安装命令如下：macOS 或 Linux:curl -LsSf https://astral.sh/uv/install.sh | shWindows:powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"第二步：安装arxiv-mcp-server使用uv tool install命令进行全局安装。这个命令会将arxiv-mcp-server可执行文件添加到你的PATH中。基础安装（支持HTML格式论文）：uv tool install arxiv-mcp-server如果你需要处理那些只有PDF格式的较老论文，请安装PDF支持扩展：uv tool install 'arxiv-mcp-server[pdf]'第三步：配置你的MCP客户端以Claude Desktop为例。找到其配置文件：macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json使用文本编辑器打开该文件，添加以下配置。你可以通过--storage-path参数指定论文的存储位置（默认为~/.arxiv-mcp-server/papers）。{ "mcpServers": { "arxiv": { "command": "uv", "args": ["tool", "run", "arxiv-mcp-server", "--storage-path", "/你/想/存储/论文/的/路径"] } } }如果你已经通过uv tool install安装了服务器，也可以直接使用arxiv-mcp-server命令：{ "mcpServers": { "arxiv": { "command": "arxiv-mcp-server", "args": ["--storage-path", "/你/想/存储/论文/的/路径"] } } }对于Windows用户，如果直接命令不生效，可以尝试用cmd包装：{ "mcpServers": { "arxiv": { "command": "cmd", "args": ["/c", "uv", "tool", "run", "arxiv-mcp-server", "--storage-path", "C:\\你\\想\\存储\\论文\\的\\路径"] } } }第四步：重启并验证保存配置文件，完全退出Claude Desktop并重新启动。在新的对话中，尝试提问：“请帮我搜索arXiv上关于‘Model Context Protocol’的论文，只返回5篇。”如果配置成功，AI会调用search_papers工具，并返回一个包含标题、作者、摘要和链接的论文列表。五、使用示例配置完成后，你就可以像指挥一位学术助理一样，让AI帮你进行各类学术文献操作了。示例一：基础搜索你问：“搜索arXiv上2025年以后关于‘Transformer模型优化’的论文，分类选cs.LG和cs.CL，按日期排序，返回10篇。”AI会调用search_papers，设置query、date_from、categories和sort_by参数。示例二：下载并阅读论文你问：“请下载论文ID为2401.12345的论文，然后读取它的全文，用中文总结一下摘要部分。”AI会先调用download_paper，再调用read_paper，然后基于全文进行总结。示例三：深度论文分析你问：“请对arXiv ID为2404.19756的论文进行深度分析。”AI会调用内置的deep-paper-analysis提示。这个提示会指导AI：先检查是否已下载，如果没有则下载，然后阅读全文，并按照执行摘要、方法论、实验结果、贡献和局限性的结构进行分析。示例四：语义搜索（需先下载论文）你问：“在我的本地论文库里，有哪些论文和‘test-time adaptation’这个概念最相关？”AI会调用semantic_search，设置query: "test-time adaptation"，然后返回相似度最高的几篇论文。示例五：设置研究监控你问：“请帮我监控主题‘量子机器学习’的新论文，每周检查一次，有新论文时告诉我。”AI会调用watch_topic设置监控，之后你可以通过check_alerts获取更新。六、常见问题问题一：安装后运行提示“command not found: arxiv-mcp-server”。解决方案：这通常是因为使用uv pip install而非uv tool install安装了包。uv pip install会将包安装到当前虚拟环境，但不创建全局可执行文件。请先运行uv tool uninstall arxiv-mcp-server（如果已安装），然后改用uv tool install arxiv-mcp-server重新安装。问题二：下载某些论文时失败，尤其是较老的论文。解决方案：较老的论文可能只提供PDF格式，而没有HTML版本。基础安装的服务器只能处理HTML。请安装PDF扩展：uv tool install 'arxiv-mcp-server[pdf]'。安装后需要重启MCP客户端。对于极少数PDF都无法获取的论文，可能是arXiv本身未提供。问题三：搜索时返回速率限制错误。解决方案：arXiv API有严格的速率限制，要求每次请求间隔至少3秒。服务器内部已经实现了自动等待，但如果你的客户端在短时间内发起了大量搜索请求，仍可能触发限制。如果遇到速率限制错误，请等待60秒后重试。问题四：解析semantic_search或citation_graph功能时提示缺少依赖。解决方案：这两个功能属于“pro”特性，需要额外安装依赖。进入项目克隆目录（或工作区），运行uv pip install -e ".[pro]"（如果你是从源码运行）。如果使用的是全局工具安装，目前尚不支持pro特性，建议从源码克隆并按照开发模式配置。问题五：AI读取论文后，做出了奇怪的建议（如建议运行外部命令）。解决方案：这可能是论文内容中的提示词注入攻击。项目文档中已经警告过此风险。你应该不要盲目执行AI的建议。在对AI的建议采取行动前（特别是涉及运行命令、访问网络或修改文件时），请先人工判断。如果怀疑是恶意注入，可以忽略该建议并报告。七、总结arxiv-mcp-server是我见过的最完善的学术型MCP服务器之一。它不仅提供了基础的搜索和下载功能，更通过语义搜索、引用网络、研究监控和引导式分析提示，构建了一套完整的AI辅助研究体系。项目最令人印象深刻的是其对安全性的深刻认识。它主动、清晰地讨论了提示词注入的风险，并给出了具体可行的缓解措施。在处理外部、不可信内容的AI工具中，这种透明度是专业性的体现。对于学生、研究人员、工程师或任何需要跟进学术前沿的人，arxiv-mcp-server是一个能极大提升工作效率的工具。它将文献检索、管理、阅读和分析这些耗时的工作流，浓缩成了与AI的几句对话。尤其是watch_topic和check_alerts功能，让你能被动地接收领域动态，而非主动地反复查询。如果你从事任何形式的研究工作，或者需要系统性地了解某个技术领域，我强烈建议你立即安装arxiv-mcp-server。它不会替你思考，但它会帮你节省下大量用于信息收集和整理的时间，让你能专注于真正的创造性和判断性工作。
如果你关心搜索隐私，不希望你的每一次查询都被记录和分析，但又想让你的AI助手能够实时联网获取信息，那么如何在隐私和便利之间取得平衡？SearXNG给出了答案。searxng-mcp则是一个巧妙的桥梁，它将SearXNG这个尊重隐私的元搜索引擎的能力，通过模型上下文协议赋予了你的AI助手。searxng-mcp是一个模型上下文协议服务器，它让你的AI能够通过SearXNG执行网络搜索。SearXNG本身是一个元搜索引擎，它聚合了来自Google、Bing、DuckDuckGo等多个搜索引擎的结果，同时不会追踪你，不会记录你的IP地址，也不会建立你的个人画像。通过这个服务器，你的AI可以在不牺牲隐私的前提下，获得实时、多元化的搜索结果。项目基本信息信息项详情项目名称searxng-mcpGitHub地址https://github.com/tisDDM/searxng-mcp项目描述A Model Context Protocol (MCP) server that enables AI assistants to perform web searches using SearXNG, a privacy-respecting metasearch engine.作者tisDDM开源协议MIT License开源状态公开状态LanguagesTypeScript, JavaScript支持平台Windows / macOS / Linux最后更新2026-04-20一、项目介绍searxng-mcp的核心是一个名为searxngsearch的工具。通过这个工具，你的AI可以执行高度可控的网络搜索，并获得格式化后的结果。这个服务器最吸引人的特点是其零配置开箱即用的设计。它默认会从SearX.space这个公共实例列表中，随机选择一个可用的SearXNG实例。这意味着你不需要注册、不需要API密钥、甚至不需要自己搭建任何服务，就能立刻让AI拥有隐私保护的搜索能力。当然，如果你有自己的SearXNG私有实例，或者希望连接到一个特定的公开实例，也可以轻松配置。它还支持基本认证，适用于需要登录的私有实例。搜索工具本身提供了丰富的参数。你可以指定搜索语言、时间范围（一天到一年）、搜索类别（通用、图片、新闻等）、甚至指定特定的搜索引擎（如只从Google和维基百科搜索）。你还可以设置安全搜索级别和分页，并控制返回结果的最大数量（最多50条）。二、核心优势隐私优先，不妥协：这是该项目最核心的价值。所有的搜索请求都通过SearXNG发出，你的查询词、IP地址等隐私信息不会被任何单一的搜索引擎（如Google）直接收集。SearXNG本身的设计就是不追踪、不记录。这让你的AI助手在获取实时信息的同时，也能尊重你的数据隐私。零配置，立即使用：你不需要申请API密钥，不需要绑定信用卡，甚至不需要了解SearXNG是什么。只需要像配置其他MCP服务器一样，在客户端中添加几行配置，你的AI就能立刻进行联网搜索。这种“傻瓜式”的上手体验，大大降低了使用门槛。多搜索引擎聚合：SearXNG是一个元搜索引擎，它同时查询多个后端搜索引擎，然后将结果合并去重后返回。这意味着你的AI获得的结果是多元化的，不局限于某一家的搜索索引，有助于打破“信息茧房”。如果你的配置中指定了多个引擎，还能看到不同来源对同一查询的不同结果。灵活的搜索参数：服务器暴露了SearXNG大部分核心搜索参数。你可以让AI只搜索过去一周的新闻，或者只从“学术”类别中查找结果，或者指定使用维基百科作为唯一搜索源。这种粒度的控制力，让AI能够进行非常精准的信息挖掘。三、适用场景场景一：注重隐私的个人助手。如果你是隐私倡导者，不信任商业搜索引擎的数据收集行为，但又希望你的AI有联网能力。这个服务器是绝佳选择。你可以开箱即用，或者连接到自己托管的私有SearXNG实例，实现完全的隐私控制。场景二：快速信息查证。在对话中，你可以随时让AI：“用SearXNG搜索一下‘2026年欧洲杯赛程’，只返回来自新闻类别的结果。” AI会进行隐私搜索，并给出赛程信息。场景三：跨搜索引擎结果对比。你可以让AI对比不同搜索引擎的结果。“请分别通过Google和Bing的后台，搜索‘大语言模型’这个关键词，然后告诉我结果首页的前三条有什么不同。” 这需要SearXNG配置了这两个引擎。场景四：时效性信息检索。你可以利用time_range参数。“搜索过去一周内关于‘特斯拉新款电动车’的新闻。” AI能返回最近7天的相关报道，避免被旧信息干扰。场景五：开发隐私保护的AI应用。如果你正在开发一个AI应用，不希望因为集成了搜索API而引入隐私合规风险。可以以searxng-mcp为基础，构建你的搜索模块。它既有完整的功能，又天然具备隐私友好特性。四、安装教程searxng-mcp的安装非常快捷，因为它可以通过npm或npx直接运行。重要说明：该项目作者已宣布此仓库为“已弃用”，并推荐使用其继任者searxNcrawl。不过，当前的版本对于日常搜索功能仍然是完整可用的。如果你追求最新的功能和维护，可以考虑使用继任项目；如果想快速开始一个简单、隐私的搜索MCP，当前版本依然是一个稳定的选择。第一步：确保Node.js环境请确认你的系统已安装Node.js 16或更高版本。你可以在终端输入node --version来检查。如果未安装，请前往Node.js官网下载。第二步：配置你的MCP客户端配置文件示例以Claude Desktop为例。找到其配置文件：macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json使用文本编辑器打开该文件，添加以下配置：{ "mcpServers": { "searxngmcp": { "command": "npx", "args": ["-y", "searxng-mcp"] } } }这个配置利用了默认行为：服务器会随机选择一个公共SearXNG实例。你不需要设置任何环境变量。如果你希望连接到自己托管的私有实例，可以这样配置：{ "mcpServers": { "searxngmcp": { "command": "npx", "args": ["-y", "searxng-mcp"], "env": { "SEARXNG_URL": "https://你的searxng实例地址", "SEARXNG_USERNAME": "你的用户名", "SEARXNG_PASSWORD": "你的密码" } } } }对于Windows用户，如果npx无法直接运行，可以用cmd包装：{ "mcpServers": { "searxngmcp": { "command": "cmd", "args": ["/c", "npx", "-y", "searxng-mcp"] } } }第三步：重启并验证保存配置文件，完全退出Claude Desktop并重新启动。在新的对话中，尝试提问：“请用SearXNG搜索一下‘隐私保护’这个关键词，返回5个结果。”如果配置成功，AI会调用searxngsearch工具，并返回一个包含标题、链接和摘要的搜索结果列表。五、使用示例配置完成后，你就可以用自然语言让AI执行隐私保护的搜索了。示例一：基础搜索你问：“帮我搜索一下‘SearXNG是什么’。”AI会调用工具，使用默认参数进行搜索，然后返回结果列表。示例二：带时间范围的新闻搜索你问：“搜索过去一个月内，关于‘气候变化’的新闻，只从新闻类别中找。”AI会设置categories: ["news"]和time_range: "month"。示例三：限制结果数量和来源你问：“只从维基百科搜索‘量子计算’，给我返回3个结果。”AI会设置engines: ["wikipedia"]，max_results: 3。示例四：调整安全搜索级别你问：“搜索‘苹果公司’，使用严格的安全搜索模式。”AI会设置safesearch: 2（严格模式）。示例五：多页搜索你问：“搜索‘Python教程’，我要看第二页的结果。”AI会设置pageno: 2。六、常见问题问题一：搜索时返回“429 Too Many Requests”错误。解决方案：这是使用公共SearXNG实例时最常见的问题。429错误意味着你使用的公共实例认为来自该IP的请求过于频繁，进行了速率限制。你可以尝试：稍后再试；等待几分钟让限制重置；或者自己搭建一个私有SearXNG实例（这是最可靠的解决方案），然后在配置中指定SEARXNG_URL。问题二：服务器提示“已弃用（deprecated）”，我还能用吗？解决方案：是的，你仍然可以使用。作者标记为“已弃用”意味着未来将不再积极维护和更新，但当前的版本（v0.2.0）功能是完整的，可以正常工作。对于希望获得长期支持和最新特性的用户，建议迁移到继任项目searxNcrawl。问题三：如何确认当前使用的是哪个SearXNG实例？解决方案：默认情况下，服务器会从SearX.space列表中随机选择一个。如果你想固定使用某个特定的可靠公共实例，可以在环境变量SEARXNG_URL中指定其地址。一些已知稳定的公共列表可以在SearXNG官方文档或社区中找到。问题四：max_results参数最大真的只能到50吗？解决方案：是的，这是目前服务器的限制。SearXNG API本身可以返回更多，但50条对于大多数AI使用场景已经足够。如果你需要更多结果，可以调整搜索关键词使其更精准，或者进行多次分页查询（使用pageno参数）。问题五：我可以指定搜索的物理位置（地区）吗？解决方案：目前服务器没有暴露明确的region或location参数。不过，SearXNG实例本身的地理位置会影响其结果倾向（例如，美国托管的实例可能更偏向英文、美国结果）。连接到不同地区的实例可以达到类似地区切换的效果。未来继任项目可能会增加此参数。七、总结searxng-mcp是一个具有鲜明特色的MCP服务器。在几乎所有其他搜索MCP都在引导你使用商业API密钥时，它选择了一条不同的路：尊重隐私、零配置、无追踪。它通过SearXNG这个隐私友好的元搜索引擎，为AI助手提供了一个干净、自由的信息获取渠道。这个项目最大的价值在于其理念和简便性。它证明了，联网搜索不一定以牺牲隐私为代价。它的零配置特性，让任何用户都能在几秒钟内为AI添加搜索能力，而不必经历注册开发者账号、申请API密钥的繁琐流程。当然，项目也有一些局限性。使用公共实例时可能遭遇速率限制，且项目本身已标记为弃用，未来的维护和支持需要依赖社区或其继任者。但对于个人使用、隐私敏感或仅仅是想要快速体验AI联网搜索的用户来说，它依然是一个非常棒的选择。如果你重视数字隐私，或者只是希望以最无痛的方式让你的AI获得搜索能力，searxng-mcp值得你立刻尝试。它让你看到，AI与隐私，可以共存。