1. 项目概述:为AI助手装上“韩国本地搜索”的眼睛

如果你和我一样,经常需要处理与韩国市场、产品、文化相关的内容,那你一定遇到过这个痛点:无论是Claude、Cursor还是其他AI助手,当你想让它帮你查一下韩国本地的商品价格、看看韩国网友的真实评价,或者了解一下韩国最新的新闻动态时,它给出的信息要么是过时的,要么干脆就是错的。原因很简单,这些AI模型的知识库是全球性的,对于韩国这种互联网生态高度本地化、信息壁垒比较明显的市场,它们很难触达最核心、最鲜活的数据源。

这就是 uju777/mcp-server-naver-search 这个项目诞生的背景。它本质上是一个 Model Context Protocol (MCP) 服务器 ,专门为 Anthropic 的 Claude Desktop、Claude Code 以及 Cursor 编辑器,搭建了一座通往 Naver(네이버) 的桥梁。Naver 是什么?你可以把它理解为韩国的“百度+淘宝+微博+知乎”综合体,是韩国人日常生活中绝对离不开的国民级应用。无论是购物比价、查找社区攻略、阅读新闻,还是看博主的深度评测,Naver 都是第一选择。

这个 MCP 服务器的核心价值,就是让 AI 助手能直接调用 Naver 的官方搜索 API,获取一手、实时、高相关性的韩国本地信息。想象一下,你可以直接问 Claude:“帮我查查三星 Galaxy S24 在 Naver 购物上的最低价和用户评价”,或者“找找首尔弘大附近最近有什么新开的网红咖啡店,看看 Naver 博客上怎么说的”。AI 不再是基于陈旧或间接的信息进行推测,而是能像一名熟练的韩国网民一样,直接“看到”Naver 上的真实内容。

我花了一周时间,从申请 API 到配置部署,再到实际测试各种搜索场景,把这个工具彻底跑通了。整个过程踩了不少坑,也总结出了一套能让它稳定、高效工作的配置方法和使用技巧。接下来,我就把这套完整的实战经验分享给你,无论你是开发者、跨境电商从业者、内容研究者,还是单纯对韩国信息有需求的人,都能跟着这篇指南,亲手给你的 AI 助手装上这双“本地化”的眼睛。

2. 核心原理与架构拆解:MCP 如何让 AI “学会”搜索

在动手之前,我们得先搞清楚这个工具是怎么工作的。知其然更要知其所以然,这样后面遇到问题你才知道从哪里下手解决。

2.1 Model Context Protocol (MCP):AI 的“外挂技能包”

你可以把 MCP 理解为一个标准化的插件协议。像 Claude 这样的 AI 模型,它的核心能力是理解和生成语言,但它本身并不具备“实时搜索网络”这个功能。MCP 定义了一套通信规范,允许外部的服务器(就像我们这个 Naver Search Server)向 AI 模型“注册”自己具备的新能力(在 MCP 里叫 Tools Resources )。

当你在 Claude 的对话窗口中输入“帮我查查…”,Claude 会先判断你的意图。如果它发现自己的内置能力无法满足(比如需要实时数据),它就会去查询已连接的 MCP 服务器,看看有没有服务器提供了相关的 Tool。我们的 Naver Search Server 就提供了诸如 search_naver_shopping search_naver_cafe 这样的 Tools。Claude 识别到匹配后,就会调用这个 Tool,将你的查询关键词发送给我们的服务器。服务器收到请求后,再去调用真正的 Naver API 获取结果,整理成结构化的数据返回给 Claude。最后,Claude 再将这些数据融入它的回答中,呈现给你。

整个过程对用户是透明的,你感觉就像是 Claude 自己“会”搜索 Naver 了一样。这比传统的“复制关键词 -> 打开浏览器 -> 搜索 -> 复制结果 -> 粘贴给 AI”的流程,效率提升了不止一个量级。

2.2 项目架构与数据流

这个 MCP 服务器的代码结构非常清晰,核心就是一个 Python 脚本( server.py ),它基于 mcp 这个官方 Python SDK 开发。我们来拆解一下它的内部工作流程:

  1. 初始化与注册 :服务器启动时,会向连接的 AI 客户端(Claude Desktop 等)宣告:“嗨,我这里有四个工具可以用哦:购物搜索、咖啡厅社区搜索、新闻搜索、博客搜索。”
  2. 请求拦截与转发 :当 AI 客户端发起一个搜索请求时,服务器会根据工具类型,构造符合 Naver Search API 要求的 HTTP 请求。这里的关键是参数映射,比如将“显示数量”映射为 API 的 display 参数,将“排序方式”映射为 sort 参数。
  3. API 调用与认证 :服务器使用你配置的 NAVER_CLIENT_ID NAVER_CLIENT_SECRET ,以 HTTP Header 的形式添加到请求中,完成对 Naver 开放平台的认证。这是整个链条安全性的基础。
  4. 响应处理与格式化 :服务器收到 Naver API 返回的 JSON 数据后,不会原样扔给 AI。它会进行关键信息提取、清洗和格式化,比如从商品信息中提取标题、价格、链接、商家;从博客文章中提取标题、摘要、博主名称、发布时间等。格式化后的数据结构更清晰,便于 AI 理解和总结。
  5. 结果返回 :处理好的结构化数据最终返回给 AI 客户端,完成一次完整的 Tool 调用。

为什么选择 Naver API 而非爬虫? 这是项目设计上一个非常明智的选择。直接爬取 Naver 网页不仅违反其服务条款,面临 IP 被封禁的风险,而且网页结构复杂多变,维护成本极高。Naver 官方提供的 Search API 稳定、合法、数据结构规范,虽然免费额度有限(每日 25,000 次),但对于个人和大多数商业场景的检索需求来说,完全足够。这体现了开发者对可持续性和合规性的重视。

2.3 环境与工具选型解析

项目依赖的核心工具是 uv ,这是一个用 Rust 写的、速度极快的 Python 包管理器和项目运行器。它比传统的 pip + venv 组合要快得多,并且能很好地处理依赖隔离。项目选择 uv 来运行,确保了跨平台(macOS, Windows, Linux)环境的一致性,避免了“在我机器上好好的”这类问题。

其他依赖如 httpx (用于 HTTP 请求)和 python-dotenv (用于管理环境变量)都是现代 Python 异步和配置管理的首选库,轻量且高效。整个技术栈的选择体现了“用对工具,事半功倍”的思路。

3. 从零开始的完整配置实战

理论懂了,我们开始动手。这部分我会手把手带你完成从申请 API 到最终在 Claude 里成功搜索的全过程,并附上我踩坑后总结的每一个细节。

3.1 第一步:获取 Naver Developers API 密钥

这是整个流程的敲门砖,也是最容易卡住新手的环节。

  1. 访问与注册 :打开 Naver Developers 页面。如果你没有 Naver 账号,需要先注册一个。这里有个小坑:注册时可能需要韩国手机号验证。对于海外用户,可以尝试使用一些提供韩国虚拟手机号接收短信的服务,或者寻找有韩国朋友的帮助。这是访问许多韩国服务的常见门槛。
  2. 创建新应用 :登录后,点击“应用注册”。在“应用名”里,填写一个你能识别的名字,比如 “My Claude Search Tool”。“使用服务”一定要选择 Search (검색) 。其他信息如“홈페이지URL”(主页URL),如果你没有,可以填写 http://localhost 或你的 GitHub 主页地址,Naver 对此校验不严格。
  3. 关键配置:环境设置 。创建成功后,进入应用管理页面。找到 “환경 설정” (Environment Settings) “API 설정” (API Setting) 标签页。这里你需要添加至少一个“웹 서비스 환경”(Web Service Environment)。
    • 서비스 URL : 填写 http://localhost
    • 서비스 환경 : 选择 Development Production 均可,对于本地 MCP 服务器, Development 即可。
    • 비즈니스 등록번호 : 个人开发者通常没有,可以留空或填写一串虚拟数字(如 123-45-67890),系统有时会做格式校验但不一定严格验证真实性。
  4. 获取密钥 :环境添加成功后,回到应用概览页,你就能看到你的 Client ID Client Secret 。把它们妥善保存下来,下一步就要用到。

实操心得:关于 API 调用限额 Naver Search API 的免费限额是每天 25,000 次请求。听起来很多,但要注意, 每次搜索,无论你请求返回10条还是100条结果,都算作1次请求 。所以对于个人日常使用,这个额度几乎是无限的。但如果你计划集成到高频调用的自动化流程中,就需要监控用量,必要时考虑 Naver 的付费套餐。

3.2 第二步:本地部署 MCP 服务器

有了密钥,我们开始部署服务器代码。

  1. 克隆项目代码 :打开你的终端(命令行),找一个合适的目录,执行:

    git clone https://github.com/uju777/mcp-server-naver-search.git
    cd mcp-server-naver-search
    

    如果没安装 git,你也可以直接在 GitHub 页面下载 ZIP 包并解压。

  2. 安装 uv :如果你的系统还没有 uv ,强烈建议安装它。在终端执行以下命令之一:

    • macOS/Linux :
      curl -LsSf https://astral.sh/uv/install.sh | sh
      
      安装后,重启终端或运行 source ~/.bashrc (或 source ~/.zshrc ) 使命令生效。
    • Windows (Powershell) :
      powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
      

    安装完成后,在终端输入 uv --version 确认安装成功。

  3. (可选)创建虚拟环境并安装依赖 :项目推荐直接用 uv run 来执行,它会自动处理依赖。但如果你想显式安装依赖到虚拟环境,可以:

    uv venv  # 创建虚拟环境
    source .venv/bin/activate  # 激活 (Linux/macOS)
    # 对于 Windows: .venv\Scripts\activate
    uv pip install -e .  # 安装项目及其依赖
    

    不过,根据项目提供的配置示例,更推荐直接使用 uv run 的方式,这样配置更简洁。

3.3 第三步:配置 Claude Desktop(最常用场景)

这是最核心的配置环节,不同客户端的配置方式略有差异,我们一个一个来。首先是最常用的 Claude Desktop。

  1. 定位配置文件 :Claude Desktop 的 MCP 配置文件通常位于:

    • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows : %APPDATA%\Claude\claude_desktop_config.json
    • Linux : ~/.config/Claude/claude_desktop_config.json 如果文件或目录不存在,你需要手动创建。
  2. 编辑配置文件 :用任何文本编辑器(如 VS Code、Notepad++)打开这个 JSON 文件。如果文件是空的,就从一对花括号 {} 开始写。你需要添加一个 mcpServers 字段。 非常重要:请将 /YOUR/PATH/TO/mcp-server-naver-search/server.py 替换为你电脑上 server.py 文件的真实绝对路径。 以下是完整的配置示例,我加了详细注释:

    {
      "mcpServers": {
        "naver-search": { // 给这个服务器起个名字,可以自定义
          "command": "uv",
          "args": [
            "run",
            "--with", "mcp[cli]", // 声明需要 mcp 的 CLI 组件
            "--with", "httpx",    // 声明需要 httpx 库
            "--with", "python-dotenv", // 声明需要 python-dotenv 库
            "/Users/yourusername/Projects/mcp-server-naver-search/server.py" // 【必须修改】你的 server.py 绝对路径
          ],
          "env": { // 在这里注入你的 Naver API 密钥
            "NAVER_CLIENT_ID": "YOUR_ACTUAL_CLIENT_ID_HERE",
            "NAVER_CLIENT_SECRET": "YOUR_ACTUAL_CLIENT_SECRET_HERE"
          }
        }
      }
    }
    

    踩坑记录:路径与引号

    • Windows 用户注意 :路径中的反斜杠 \ 需要转义,或者直接使用正斜杠 / 。例如: "C:/Users/YourName/Documents/mcp-server-naver-search/server.py"
    • 路径包含空格 :如果路径中有空格,整个路径需要用双引号包裹,但 JSON 字符串本身已经有双引号了,所以需要转义。例如: \"C:/My Projects/naver search/server.py\" 。最省事的办法是把项目放在一个没有空格的路径下。
    • 环境变量 NAVER_CLIENT_ID NAVER_CLIENT_SECRET 的值必须用双引号括起来。
  3. 保存并重启 :保存配置文件后, 完全退出 Claude Desktop 应用(不仅仅是关闭窗口,要从任务栏/程序坞退出) ,然后重新启动。这是让配置生效的关键一步。

3.4 第四步:配置 Claude Code 或 Cursor

如果你主要在使用 Claude Code(命令行版)或 Cursor 编辑器,配置方式类似,但配置文件位置和格式稍有不同。

对于 Claude Code (CLI) : 配置文件在 ~/.claude/settings.json (Linux/macOS)或 %USERPROFILE%\.claude\settings.json (Windows)。配置内容与 Claude Desktop 类似,但 command args 需要调整,因为 CLI 环境对 uv 的路径识别可能有问题。项目作者给出了一个更稳健的写法:

{
  "mcpServers": {
    "naver-search": {
      "command": "sh",
      "args": [
        "-c",
        "export PATH=\"$HOME/.local/bin:$PATH\" && cd /YOUR/PATH/TO/mcp-server-naver-search && uv run --with 'mcp[cli]' --with httpx --with python-dotenv python server.py"
      ],
      "env": {
        "NAVER_CLIENT_ID": "YOUR_ID",
        "NAVER_CLIENT_SECRET": "YOUR_SECRET"
      }
    }
  }
}

这个配置通过 sh -c 执行一段 shell 脚本,先确保 uv 所在的路径( $HOME/.local/bin )被加入环境变量,然后切换到项目目录再执行命令。这能解决大部分“command not found: uv”的问题。

对于 Cursor 编辑器 : Cursor 的 MCP 配置入口在: Settings (设置) -> Features (功能) -> MCP Servers 。你可以直接点击“Add MCP Server”进行图形化配置,也可以点击“Edit Config”手动编辑 JSON。配置的 JSON 结构与 Claude Desktop 完全一致,将那段配置粘贴进去即可。同样,记得修改路径和密钥。

3.5 第五步:验证与测试

配置完成后,如何知道成功了呢?

  1. 查看日志 :启动 Claude Desktop 后,打开“帮助”(Help)菜单,选择“打开日志目录”(Open Log Directory)。在日志文件中搜索“mcp”或“naver”,如果看到服务器成功初始化的信息,或者没有报错,通常就是成功了。
  2. 在对话中测试 :这是最直接的验证方式。在 Claude 的新对话窗口中,尝试用中文或英文(甚至韩文)提问,但 必须清晰地表达出“搜索 Naver”的意图 。例如:
    • “使用 Naver 搜索,帮我查一下最近一周关于韩国人工智能政策的新闻。”
    • “Find the lowest price for LG gram laptop on Naver Shopping.” 如果配置成功,Claude 的回复中会包含类似“I searched Naver for...”的语句,并附上结构化的搜索结果(商品列表、新闻标题等)。

4. 高级使用技巧与场景案例

基础配置搞定后,我们来探索如何把它用得更好、更聪明。这部分是我在实际使用中总结出的高效工作流。

4.1 精准搜索指令构造术

直接说“查一下咖啡机”和“在 Naver 购物上搜索‘네스프레소 버츄오 넥스트’,按价格从低到高排序,显示前10个结果”的效果是天壤之别。给你的 AI 助手更精确的指令,它能返回更精准的结果。

  • 指定搜索类型 :在问题中明确说出工具名。例如:“用 Naver Shopping 搜一下三星 갤럭시 워치7”、“去 Naver Cafe 找找济州岛自驾游的攻略”。
  • 明确排序与数量 :Naver API 支持排序参数。购物搜索可以按 sim (相关度)、 date (日期)、 asc (价格升序)、 dsc (价格降序)。你可以在指令中指定:“查一下 냉장고 (冰箱),按价格从低到高( asc )排,给我看5个最便宜的。”
  • 组合关键词与过滤 :利用韩语关键词的组合来过滤。比如想找真实用户评价,可以搜索“ [产品名] 후기 ”(后记/评价)或“ [产品名] 솔직후기 ”(真实后记)。找最新信息可以加“ 2025 ”或“ 최신 ”(最新)。

4.2 典型应用场景深度解析

  1. 跨境电商与市场调研

    • 场景 :你想把一款中国产的小家电卖到韩国。
    • 操作 :让 Claude 搜索“ 전기포트 추천 ”(电水壶推荐)或“ 미니 선풍기 ”(迷你风扇)。通过 Naver 购物和博客的结果,你可以分析: 价格区间 (韩国消费者能接受的心理价位)、 竞品特性 (哪些功能被频繁提及)、 营销痛点 (用户抱怨现有产品的什么问题,如噪音大、容量小)。Naver Cafe 里的讨论更能看到用户未经修饰的真实反馈。
    • 心得 :不要只看商品列表,多看看博客和 Cafe 的“후기”(评价)和“사용기”(使用记),那里有更丰富的使用场景和未被满足的需求。
  2. 内容创作与热点追踪

    • 场景 :你是运营韩国社交媒体账号或撰写韩国相关文章的内容创作者。
    • 操作 :每天早上让 Claude 用 Naver 新闻搜索“ 오늘 주요 뉴스 ”(今日主要新闻)或特定关键词如“ K-팝 ”、“ 한류 ”。AI 可以快速为你生成一份热点简报。或者,在写一篇关于“韩国职场文化”的文章前,搜索“ 회식 문화 ”(会食文化)、“ 워라밸 ”(Work-Life Balance)看看韩国网友最近在讨论什么。
    • 心得 :利用新闻搜索的“ sort=date ”确保获取最新信息。对于深度内容,博客搜索的结果质量通常高于新闻,因为博主会加入更多个人分析和背景知识。
  3. 旅行规划与本地生活

    • 场景 :计划去首尔旅行,想找非游客区的美食和景点。
    • 操作 :搜索“ 망원동 맛집 ”(望远洞美食店)、“ 한남동 카페 ”(汉南洞咖啡厅)。重点看 Naver Cafe 和博客,这里的推荐往往来自本地居民,比旅游攻略网站更接地气。可以进一步让 AI 总结出“地址、推荐菜、人均消费、网友评价亮点”。
    • 心得 :结合地图工具(如 Naver Map),让 AI 将搜索到的地点信息整理成一条合理的游览路线。

4.3 结果解读与信息甄别

AI 返回的搜索结果已经是结构化的,但你需要知道如何解读:

  • 购物结果 :关注 lprice (最低价)和 mallName (商家名)。对于高价商品, mallName 的信誉很重要。链接 ( link ) 可以直接点开查看详情。
  • 博客/新闻结果 :关注 postdate (发布日期)以确保信息时效性。 description (摘要)是快速判断内容相关性的关键。 bloggername (博主名)如果是你熟悉的领域 KOL,其内容权重可以调高。
  • Cafe 结果 cafename (咖啡厅名)和 title (帖子标题)能帮你快速定位到感兴趣的社区。注意,Cafe 帖子可能需要相应 Cafe 的会员身份才能阅读全文,AI 返回的摘要可能有限。

重要提醒 :AI 总结的信息是基于它“看到”的文本。对于价格、促销、库存等实时性极强的信息,以及涉及重大消费决策时, 务必通过 AI 提供的链接,跳转到原始页面进行最终确认 。AI 是一个强大的信息聚合和筛选器,但还不是最终决策者。

5. 故障排除与性能优化指南

即使按照步骤操作,你也可能会遇到一些问题。这里我整理了常见的错误和解决方法。

5.1 常见错误与解决方案

问题现象 可能原因 解决方案
Claude 启动时报错,或日志中出现 MCP 连接失败 1. uv 命令未安装或不在 PATH。
2. server.py 路径错误。
3. Python 依赖安装失败。
1. 终端执行 uv --version 验证安装。确保配置中 command 正确( uv sh )。
2. 使用绝对路径,并确保路径中的引号和转义正确(尤其 Windows)。
3. 尝试在项目目录下手动运行 uv run python server.py ,看是否报错。可能需要先运行 uv pip install -r requirements.txt (如果有的话)或 uv add mcp[cli] httpx python-dotenv
Claude 不调用 Naver 搜索,或回复“我无法搜索网络” 1. MCP 配置未生效。
2. 提问方式未触发工具调用。
3. 服务器进程启动失败。
1. 彻底重启 Claude Desktop。检查配置文件语法(可用 JSON 校验工具)。
2. 在问题中明确包含“Naver”、“搜索”等关键词。尝试用项目 README 中的示例问题。
3. 查看 Claude 日志,确认 naver-search 服务器是否在启动时被成功加载。
AI 返回“搜索失败”或“API 错误” 1. Naver API 密钥错误或未设置。
2. API 调用额度用尽。
3. 网络问题导致请求超时。
1. 仔细检查 claude_desktop_config.json env 部分的 NAVER_CLIENT_ID NAVER_CLIENT_SECRET 是否正确,且 值被双引号包裹
2. 登录 Naver Developers 控制台,查看“통계”(统计)确认今日用量。
3. 检查本地网络连接,尝试能否直接访问 https://openapi.naver.com
搜索返回结果少或不准 1. 搜索关键词不精准(尤其是韩语)。
2. 未指定合适的搜索分类( shop news 等)。
1. 使用更具体、更地道的韩语关键词。利用 Naver 本身的搜索联想功能(在 Naver 网站搜索框输入时会有提示)来获取高频关键词。
2. 在提问时明确指定搜索类型,如“用 Naver 新闻 搜索...”。

5.2 安全与隐私注意事项

  • API 密钥安全 :你的 NAVER_CLIENT_ID NAVER_CLIENT_SECRET 是私密信息。配置文件 claude_desktop_config.json 是明文存储的。请确保不要将此文件上传到公开的代码仓库(如 GitHub)。如果必须分享配置,务必先移除密钥部分。
  • 环境变量替代方案(高级) :更安全的方式是通过系统环境变量传递密钥,然后在配置文件中引用。例如,在终端中设置:
    export NAVER_CLIENT_ID="your_id"
    export NAVER_CLIENT_SECRET="your_secret"
    
    然后将配置文件中的 env 对象改为从环境变量读取(具体语法取决于你的启动器是否支持)。对于 Claude Desktop,更简单的方法是保持现有配置,但确保你的电脑物理安全。
  • 使用范围 :遵守 Naver API 的使用条款。该工具仅用于个人学习和获取公开信息,不得用于大规模爬虫、商业数据挖掘或任何违反 Naver 服务条款的行为。

5.3 性能优化建议

  • 减少不必要的调用 :在单次对话中,如果已经进行过一次搜索,后续的细化问题可以基于已有结果让 AI 进行分析,而不是频繁发起新的搜索。例如,先搜索“ 게이밍 노트북 ”(游戏笔记本),然后问“把刚才搜索结果里价格在 200 万韩元以下的型号列出来”。
  • 关键词预处理 :对于复杂查询,可以先让 AI 帮你提炼出最核心的搜索关键词,再用这些关键词去搜索,效果往往更好。
  • 管理对话上下文 :Claude 有上下文窗口限制。如果一次搜索返回了大量文本结果,可能会占用很多 tokens。可以让 AI 先进行摘要和筛选,只保留最关键的信息放入上下文,以备后续分析。

经过以上步骤,你应该已经成功搭建并开始熟练使用这个强大的 Naver 搜索桥梁了。它不仅仅是一个工具,更是一种工作流的革新——将韩国本地化信息检索这个高频但繁琐的任务,无缝嵌入到你与 AI 助手的自然对话中。从市场调研到内容创作,从旅行规划到学术研究,信息的边界被极大地拓宽了。剩下的,就是发挥你的想象力,去探索和解决那些真正需要“韩国视角”的问题了。

Logo

码道开发者社区,聚焦华为云码道 CodeArts 代码智能体,沉淀 Agent、Skill、鸿蒙开发实战内容,供开发者查阅资料、交流技术、分享工程实践

更多推荐