grokipedia-mcp

🚀 Grokipedia MCP Server

Grokipedia MCP Server 是一个用于从 Grokipedia 搜索和检索内容的服务器。用户在与 Grokipedia 进行交互时需承担全部责任。若有任何疑问，请参阅 Xai 服务条款。

🚀 快速开始

将以下内容添加到您的 MCP 配置文件中：

{
  "mcpServers": {
    "grokipedia": {
      "command": "uvx",
      "args": ["grokipedia-mcp"]
    }
  }
}

验证安装

您可以通过以下工具查看 Grokipedia 服务器是否可用：

• search - 带过滤条件的搜索
• get_page - 获取页面概述
• get_page_content - 获取完整内容
• get_page_citations - 获取引用
• get_related_pages - 获取链接页面
• get_page_sections - 列出所有章节标题
• get_page_section - 提取特定章节

以及以下提示词：

• research_topic - 研究工作流程
• find_sources - 查找引用
• explore_related - 探索关联内容
• compare_topics - 比较两个主题

✨ 主要特性

• 带过滤条件的搜索：支持按相关性或浏览量排序，以及按最小浏览量过滤。
• 页面内容获取：可检索文章、引用和元数据，并进行智能截断。
• 相关页面发现：能发现链接或相关的文章。
• 章节提取：可从长篇文章中提取特定章节。
• 智能建议：当页面未找到时提供有用的替代建议。
• 引导式提示词：提供预建的研究、查找引用和探索关联内容的工作流程。

📦 安装指南

开发环境安装

使用 uv 进行安装：

cd grokipedia-mcp
uv sync

若要使用 MCP Inspector 和 CLI 工具进行开发：

uv sync --dev

💻 使用示例

使用 MCP Inspector 运行（开发环境）

这是测试和调试的最快方法（需要开发依赖）：

uv run --dev mcp dev main.py

运行上述命令后，会启动 MCP Inspector UI，您可以在其中：

• 探索可用工具
• 测试搜索查询
• 检索页面内容
• 查看结构化输出

直接运行

# 使用已安装的入口点
uv run grokipedia-mcp

# 或作为 Python 模块运行
uv run python -m grokipedia_mcp

# 或直接运行
uv run python main.py

可用工具示例

search

在 Grokipedia 中搜索文章，支持过滤和排序选项。

参数：

• query（字符串，必需） - 搜索查询词
• limit（整数，可选，默认值：12） - 最大结果数
• offset（整数，可选，默认值：0） - 分页偏移量
• sort_by（字符串，可选，默认值："relevance"） - 按 "relevance" 或 "views" 排序
• min_views（整数，可选） - 过滤出至少有指定浏览量的文章

返回值：包含标题、slug、摘要、相关性得分和浏览量的搜索结果列表。

示例：

// 基本搜索
{"query": "machine learning", "limit": 5}

// 按浏览量排序
{"query": "python", "sort_by": "views"}

// 仅过滤热门文章
{"query": "artificial intelligence", "min_views": 1000}

get_page

获取完整的页面信息，包括元数据、内容预览和引用摘要。如果页面未找到，会提供智能的替代建议。

参数：

• slug（字符串，必需） - 文章标识符（来自搜索结果）
• max_content_length（整数，可选，默认值：5000） - 最大内容长度

返回值：包含元数据、截断内容和引用摘要的完整页面对象。

特性：

• 如果请求的 slug 不存在，会建议类似页面
• 提供包含内容预览和引用的概述

适用场景：当您需要带有元数据和内容预览的页面概述时使用。

示例：

{"slug": "Machine_learning"}

get_page_content

仅获取文章内容，不包含引用或元数据。

参数：

• slug（字符串，必需） - 文章标识符
• max_length（整数，可选，默认值：10000） - 最大内容长度

返回值：仅包含文章内容（标题和内容文本）。

适用场景：当您需要阅读不包含引用的完整文章内容时使用。

示例：

{"slug": "Machine_learning", "max_length": 15000}

get_page_citations

获取特定页面的引用列表。

参数：

• slug（字符串，必需） - 文章标识符
• limit（整数，可选） - 要返回的最大引用数（如果未指定，则返回所有引用）

返回值：包含标题、URL 和描述的引用列表。包括总数和返回数。

适用场景：当您需要访问源引用和引用时使用。

示例：

// 获取所有引用
{"slug": "Machine_learning"}

// 仅获取前 10 个引用
{"slug": "Machine_learning", "limit": 10}

get_related_pages

获取特定文章链接的页面。

参数：

• slug（字符串，必需） - 文章标识符
• limit（整数，可选，默认值：10） - 要返回的最大相关页面数

返回值：包含标题和 slug 的相关/链接页面列表。

适用场景：当您想发现相关主题或探索文章之间的关联时使用。

示例：

// 获取相关页面
{"slug": "Machine_learning"}

// 获取更多相关页面
{"slug": "Quantum_computing", "limit": 20}

get_page_sections

获取文章中所有章节标题的列表。

参数：

• slug（字符串，必需） - 文章标识符

返回值：包含所有章节标题及其级别（h1、h2、h3 等）的列表。

适用场景：当您想在阅读特定章节之前查看文章的结构/大纲时使用。

示例：

{"slug": "Machine_learning"}

get_page_section

按标题名称从文章中提取特定章节。

参数：

• slug（字符串，必需） - 文章标识符
• section_header（字符串，必需） - 要提取的章节标题（不区分大小写）
• max_length（整数，可选，默认值：5000） - 最大章节内容长度

返回值：仅包含指定章节的内容。

适用场景：当您只需要长篇文章的一个章节（例如，"应用"、"历史"、"示例"）时使用。

示例：

// 获取特定章节
{"slug": "Neural_networks", "section_header": "Applications"}

// 获取更长的章节
{"slug": "Python", "section_header": "Syntax", "max_length": 10000}

注意：文章可能超过 100,000 个字符。为防止超出大语言模型的上下文窗口，内容会自动截断。您可以使用 max_length 参数控制返回的内容量。

提示词示例

服务器提供了用于常见工作流程的预建提示词：

research_topic

引导式工作流程，用于研究主题：搜索 → 检索 → 分析相关页面和引用

find_sources

为学术/研究目的查找权威来源和引用

explore_related

发现主题之间的关联并获取推荐的进一步阅读内容

compare_topics

并排比较两个主题的内容和引用

🔧 技术细节

架构

服务器使用了以下技术：

• FastMCP 用于声明式 MCP 服务器实现
• grokipedia-api-sdk AsyncClient 用于 API 通信
• Lifespan context 用于客户端连接管理
• Structured output 使用 SDK 中的 Pydantic 模型
• Comprehensive error handling 具备特定的异常类型

错误处理

服务器处理各种错误场景：

• ValueError 用于处理无效参数或页面未找到的情况
• RuntimeError 用于处理网络或 API 错误
• 支持详细的调试、信息、警告和错误级别的日志记录

开发

项目结构

grokipedia-mcp/
├── grokipedia_mcp/
│   ├── __init__.py       # 包导出
│   ├── __main__.py       # CLI 入口点
│   └── server.py         # FastMCP 服务器实现
├── main.py               # 直接执行入口点
├── pyproject.toml        # 项目配置
└── README.md             # 本文件

测试

使用 MCP Inspector 进行交互式测试：

uv run mcp dev main.py

📄 许可证

本项目采用 MIT 许可证。