项目简介

本项目是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在通过标准化的接口，为大型语言模型 (LLM) 客户端提供访问 Naver 搜索 API 的能力。它允许 LLM 调用工具执行搜索操作，并获取结构化的搜索结果作为上下文信息。

主要功能点

多种搜索类别： 支持搜索 Naver 上的博客、新闻、书籍、图片、购物商品、百科、知识iN、本地信息等。
分页支持： 大部分搜索工具支持通过指定页码 ('page') 和每页显示数量 ('display') 进行结果分页。
结构化响应： 将 Naver API 返回的原始数据格式化为对 LLM 更友好的结构化文本格式。
实用工具： 包含检查搜索词是否为成人内容 ('check_adult_query') 和校正键盘输入错误 ('correct_errata') 的工具。
能力声明： 通过 MCP 协议声明可用的搜索类别资源和各项搜索工具。

安装步骤

前提条件：
- Python 3.12 或更高版本。
- Naver Developer API 凭据（Client ID 和 Client Secret）。请前往 Naver Developers 注册获取。

克隆仓库：

git clone https://github.com/jikime/py-mcp-naver-search.git
cd py-mcp-naver-search

安装 uv (推荐)：

curl -LsSf https://astral.sh/uv/install.sh | sh

如果您不想使用 'uv'，也可以直接使用 'python -m venv .venv' 和 'pip install -r requirements.txt'。

创建并激活虚拟环境：

uv venv -p 3.12 # 或 python -m venv .venv
source .venv/bin/activate

安装依赖：

pip install -r requirements.txt

配置 Naver API 凭据：

复制 '.env.example' 文件为 '.env'。

cp env.example .env

编辑 '.env' 文件，填入您的 Naver Client ID 和 Client Secret。

NAVER_CLIENT_ID=您的Client ID
NAVER_CLIENT_SECRET=您的Client Secret

服务器配置 (供 MCP 客户端使用)

MCP 服务器通常由 MCP 客户端（如支持 MCP 的 AI 应用或 IDE）启动和管理。您需要在您的 MCP 客户端的配置文件中添加以下配置，以告知客户端如何启动和连接到此服务器。

典型的 MCP 客户端配置文件（JSON 格式）会有一个 'mcpServers' 部分。请根据您的客户端类型（例如，Claude 桌面应用、Cursor IDE）将以下配置添加到 'mcpServers' 对象中。

{
  "mcpServers": {
    "Naver Search": {
      "command": "uv",  // 或您环境中 Python 解释器的路径，如 "/path/to/your/python3.12"
      "args": [
        "--directory",
        "/path/to/py-mcp-naver-search",  // 将此路径替换为您实际克隆仓库的目录路径
        "run",
        "server.py"
      ]
      // 如果使用 Docker:
      // "command": "docker",
      // "args": [
      //   "run",
      //   "-i",
      //   "--rm",
      //   "py-mcp-naver-search" // 您的 Docker 镜像名称
      // ]
    }
    // 其他 MCP 服务器配置...
  }
}

将 '"command"' 设置为 'uv' 或您的 Python 解释器路径。
将 '"/path/to/py-mcp-naver-search"' 替换为您克隆本项目的实际目录路径。
'args' 参数告诉 'uv' 或 Python 解释器在指定目录下运行 'server.py' 文件。
如果使用 Docker 部署，请使用 Docker 的 'command' 和 'args' 配置（需要先构建 Docker 镜像）。

配置完成后，您的 MCP 客户端即可识别并使用此 Naver 搜索 MCP 服务器提供的能力。

基本使用方法

一旦服务器被 MCP 客户端成功配置并启动，LLM 即可通过 MCP 协议调用服务器暴露的 Tools。例如，LLM 可以调用名为 'search_blog' 的 Tool 来搜索博客文章，调用 'search_news' 来搜索新闻等，并指定 'query'、'display'、'page' 等参数。

本项目也提供了一个简单的客户端脚本 ('client.py') 用于测试：

确保您已激活虚拟环境 ('source .venv/bin/activate')。

使用以下命令格式运行客户端：

uv run client.py <category> <query> [param1=value1] [param2=value2] ...

'<category>': 搜索类别，如 'blog', 'news', 'shop', 'image', 'errata' 等。
'<query>': 搜索关键词。如果包含空格，请使用引号括起来。
'[param=value]': 可选参数，如 'display=10', 'page=1', 'sort=date', 'filter=large' 等，根据不同 Tool 支持的参数填写。

示例：

uv run client.py blog "Python MCP" display=5 page=1
uv run client.py news AI sort=date
uv run client.py errata "spdlqj"

客户端将启动服务器（如果尚未运行），调用相应的 Tool，并打印返回的结构化文本结果。

关键词

项目简介

主要功能点

安装步骤

服务器配置 (供 MCP 客户端使用)

基本使用方法

信息