Yandex Search MCP

](https://nodejs.org)     ](https://github.com/bpawnzZ/yandex-search-mcp) ](https://github.com/bpawnzZ/yandex-search-mcp)

┌─────────────────────────────────────────────────────────────┐
│  🔍 Yandex Search MCP - Unofficial Community Project        │
│  ⚡ Powered by Playwright + TypeScript + MCP Framework       │
│  🚀 Enhanced with Content Extraction & LLM Context          │
└─────────────────────────────────────────────────────────────┘

⚠️ 重要免责声明 这是一个 非官方社区项目 并且不隶属于、认可或关联于： - Yandex有限责任公司 （搜索引擎提供商） - Anthropic （克劳德和MCP的创造者） - 谷歌 （剧作家维护者） 此工具使用浏览器自动化来访问Yandex搜索。用户负责： - 遵守Yandex的服务条款 - 遵守费率限制和机器人政策 - 使用自己的身份验证Cookie - 不将此工具用于恶意目的

📋 目录

• ✨ 特性
• 🚀 快速开始
• 📦 安装
• 🍪 Cookie设置
• ⚙️ 配置
• 🎯 用法
• 🔧 工具
• 🏗️ 建筑
• 🛠️ 故障排除
• 🤝 贡献
• 📄 许可证

✨ 特性

核心能力

增强功能（v2.0）

🚀 快速开始

# 1. Clone the repository
git clone https://github.com/bpawnzZ/yandex-search-mcp.git
cd yandex-search-mcp

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Configure cookies (see Cookie Setup section)
# 5. Add to MCP client configuration
# 6. Start searching! 🎉

📦 安装

先决条件

• Node.js 18+
• npm或纱线
• Yandex帐户（用于Cookie）
• Cookie编辑器浏览器扩展程序（或类似程序）

选项1：克隆和构建

git clone https://github.com/bpawnzZ/yandex-search-mcp.git
cd yandex-search-mcp
npm install
npm run build

选项2：与npx一起使用（发布后）

npx yandex-search-mcp

🍪 Cookie设置

为什么饼干？

Yandex对自动请求实施验证码挑战。使用经过身份验证的Cookie允许该工具绕过这些挑战并无缝执行搜索。

获取您的Cookie

1. 安装Cookie编辑器扩展：

- 铬： Cookie编辑器扩展 - 火狐浏览器： Cookie编辑器插件

1. 登录Yandex：

- 首选 yandex.com - 登录您的Yandex帐户（或创建一个） - 执行搜索以确保设置了Cookie

1. 导出Cookie：

- 单击浏览器中的Cookie编辑器图标 - 点击“导出”按钮（或JSON格式） - 复制JSON数组

1. 保存Cookie：

- 将JSON粘贴到 cookies/yandex-cookies.json - 确保文件是有效的JSON

Cookie文件结构示例

[
  {
    "domain": ".yandex.com",
    "expirationDate": 1800000000.000000,
    "hostOnly": false,
    "httpOnly": true,
    "name": "Session_id",
    "path": "/",
    "sameSite": "no_restriction",
    "secure": true,
    "session": false,
    "storeId": null,
    "value": "YOUR_SESSION_ID_HERE"
  }
]

重要提示： 确保您的Cookie安全，不要将其提交到公共存储库！

⚙️ 配置

MCP客户端配置

克劳德桌面版

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "yandex-search": {
      "command": "node",
      "args": ["/path/to/yandex-search-mcp/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Cline（VS代码扩展）

添加 ~/.kilocode/mcp.json:

{
  "mcpServers": {
    "yandex-search": {
      "command": "node",
      "args": ["/home/insomnia/git/yandex-search-mcp/dist/index.js"]
    }
  }
}

环境变量

# Optional configuration
MAX_PAGES_PER_QUERY=5        # Default: 3
MAX_TOKENS_PER_PAGE=4000     # Default: 3000
CACHE_TTL_HOURS=24          # Default: 24

🎯 用法

基本搜索

// Simple search - returns titles, URLs, snippets
{
  "tool": "yandex_search",
  "params": {
    "query": "artificial intelligence",
    "numResults": 10,
    "region": "com",
    "language": "en"
  }
}

通过内容提取增强搜索

// Enhanced search - fetches and analyzes page content
{
  "tool": "yandex_search_enhanced",
  "params": {
    "query": "artificial intelligence benefits",
    "numResults": 5,
    "region": "com",
    "fetch_content": true,
    "max_pages": 3,
    "max_tokens_per_page": 3000,
    "analysis_level": "detailed",
    "context_format": "synthesized"
  }
}

输出格式

增强的工具支持多种输出格式：

示例响应（综合）

{
  "summary": "Based on 3 sources (12,456 words analyzed), here is what we found about \"artificial intelligence benefits\":",
  "key_findings": [
    {
      "source": "example.com",
      "finding": "AI increases productivity by 40% in manufacturing",
      "confidence": "high"
    }
  ],
  "synthesized_knowledge": "Synthesis of findings...",
  "source_references": [
    {
      "url": "https://example.com/ai-benefits",
      "title": "AI Benefits in 2026",
      "key_points": ["Increased productivity", "Cost reduction"],
      "relevance_note": "Relevance score: 85.3/100"
    }
  ],
  "metadata": {
    "query": "artificial intelligence benefits",
    "total_results": 500,
    "pages_fetched": 3,
    "successful_extractions": 3,
    "total_time_ms": 28500
  }
}

🔧 工具

yandex_search（基本）

简单的搜索工具，返回标题、网址和片段。

参数：

• query （字符串，必填）：搜索查询
• numResults （数字，可选）：结果数量（默认值：10，最大值：50）
• region （字符串，可选）：地区代码（默认：“com”）
• language （字符串，可选）：语言代码（默认值：“en”）
• safeSearch （布尔值，可选）：启用安全搜索（默认值：true）

yandex_search_enhanced（高级）

具有内容提取和分析功能的全功能搜索。

参数：

• 所有基本参数加上：
• fetch_content （布尔值，可选）：获取页面内容（默认值：true）
• max_pages （数字，可选）：要获取的最大页面数（默认值：3，最大值：10）
• max_tokens_per_page （数字，可选）：每页令牌限制（默认值：3000）
• analysis_level （枚举，可选）：“基本”|“详细”|“全面”
• context_format （枚举，可选）：“原始”|“汇总”|“合成”|“qa_ready”

🏗️ 建筑

┌──────────────────────────────────────────────────────────────┐
│                    Yandex Search MCP                          │
├──────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐     ┌──────────────────────────────────┐   │
│  │ Basic Search │     │        Enhanced Pipeline         │   │
│  │              │     │                                  │   │
│  │ • Search     │     │  ┌─────────────┐  ┌──────────┐   │   │
│  │ • Snippets   │     │  │   Browser   │→ │  Search  │   │   │
│  │ • URLs       │     │  │   Manager   │  │          │   │   │
│  └──────────────┘     │  └─────────────┘  └────┬─────┘   │   │
│                       │                        │         │   │
│                       │  ┌─────────────┐  ┌────▼─────┐   │   │
│                       │  │  Content    │  │ Extract  │   │   │
│                       │  │  Extractor  │←─┤ Content  │   │   │
│                       │  └─────────────┘  └────┬─────┘   │   │
│                       │                        │         │   │
│                       │  ┌─────────────┐  ┌────▼─────┐   │   │
│                       │  │  Relevance  │  │   Cache  │   │   │
│                       │  │   Scorer    │←─┤   (LRU)  │   │   │
│                       │  └─────────────┘  └──────────┘   │   │
│                       │                        │         │   │
│                       │  ┌──────────────────┐  │         │   │
│                       │  │  LLM Context     │←─┘         │   │
│                       │  │  Formatter       │            │   │
│                       │  └──────────────────┘            │   │
│                       │                        │         │   │
│                       │  ┌──────────────────┐  │         │   │
│                       │  │  Structured      │←─┘         │   │
│                       │  │  JSON Output     │            │   │
│                       │  └──────────────────┘            │   │
│                       └──────────────────────────────────┘   │
│                                                               │
└──────────────────────────────────────────────────────────────┘

关键组件

1. 浏览器管理器：Singleton秘密管理Playwright浏览器
2. 内容提取器：从页面中提取有意义的内容
3. 相关性评分器：按查询相关性对内容进行评分和排名
4. LLMContextFormatter：格式化输出以实现最佳LLM消耗
5. 内容缓存：具有域特定TTL的LRU缓存

🛠️ 故障排除

检测到验证码

症状： 结果包含 error: 'CAPTCHA detected'

解决方案（按有效性排序）：

1. 使用Yandex搜索API （推荐-100%可靠）：

   export YANDEX_SEARCH_API_KEY="your_api_key"
   export YANDEX_SEARCH_USER_ID="your_user_id"

看 Yandex搜索API设置 在......下面

1. 更新Cookie：从浏览器重新导出新的Cookie

1. 使用住宅代理：数据中心IP经常被标记

1. 启用FlareSolverr：添加 FLARESOLVERR_URL 环境变量

Yandex搜索API设置

避免CAPTCHA的最可靠方法是使用官方Yandex搜索API：

1. 获取API凭据:

- 访问 Yandex云搜索API - 创建服务帐户 - 使用生成API密钥 yandex.search-api.execute 范围 - 记下您的用户名

1. 配置MCP:

   {
     "mcpServers": {
       "yandex-search": {
         "command": "node",
         "args": ["/path/to/yandex-search-mcp/dist/index.js"],
         "env": {
           "YANDEX_SEARCH_API_KEY": "your_api_key_here",
           "YANDEX_SEARCH_USER_ID": "your_user_id_here"
         }
       }
     }
   }

1. 好处:

- 无验证码挑战 - 每天30000个免费请求 - 更快的响应时间 - 更可靠的结果

Cookie加载错误

症状： sameSite: expected one of (Strict|Lax|None)

解决方案： 这是由BrowserManager中的cookie规范化自动处理的。

内容未提取

症状： 页面内容为空或最少

可能的原因：

• 繁重的JavaScript（增加等待时间）
• 需要登录/付费墙
• 防刮擦措施

内存使用率高

解决方案：

• 减少 max_pages 参数
• 降低 max_tokens_per_page
• 缓存将自动删除旧条目

🤝 贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

开发指南

• 遵循TypeScript的最佳实践
• 为复杂逻辑添加注释
• 更新新功能的文档
• 提交前进行彻底测试

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• MCP框架 -驱动此工具的框架
• 剧作家 -浏览器自动化
• Yandex -搜索引擎（非官方使用）

📞 支持

• 问题：
• 讨论：

______________________________________________________________________

制作⚡ 为了社区，为了社区。

*这是一个非官方工具。请负责任地使用并尊重Yandex的服务条款。*