doudou/funstat-mcp

Fork 0

Files

你的用户名 a05a7dd40e chore: initial commit

2025-11-01 21:58:03 +08:00

14 KiB

Raw Permalink Blame History

Funstat MCP Server - 快速开始教程

欢迎使用 Funstat MCP Server！本教程将手把手教你如何在 5 分钟内 完成配置，让你能够通过 Claude Code 访问 10 亿+ Telegram 用户数据。

📋 前置要求检查

在开始之前，请确保你已经具备：

✅ macOS 系统（本教程基于 macOS，其他系统类似）
✅ Python 3.10+ 已安装
✅ Claude Code 已安装
✅ Session 文件 已创建（funstat_bot_session.session）

检查 Python 版本

打开终端，运行：

python3 --version

应该看到类似输出：

Python 3.10.0 或更高版本

如果 Python 版本过低，请先升级 Python。

🚀 第一步：安装依赖（2分钟）

1.1 打开终端

方法 1: 按 Cmd + Space，输入 "Terminal"，按回车

方法 2: 打开 Finder → 应用程序 → 实用工具 → 终端

1.2 进入项目目录

在终端中运行：

cd /Users/lucas/chat--1003255561049/funstat_mcp

1.3 安装 Python 依赖

运行以下命令：

pip3 install -r requirements.txt

预期输出：

Collecting telethon>=1.34.0
  Downloading telethon-1.34.0-py3-none-any.whl
Collecting mcp>=0.9.0
  Downloading mcp-0.9.0-py3-none-any.whl
...
Successfully installed telethon-1.34.0 mcp-0.9.0 pydantic-2.5.0

如果遇到权限错误，使用：

pip3 install --user -r requirements.txt

1.4 验证安装

运行：

python3 -c "import telethon; import mcp; print('✅ 依赖安装成功！')"

应该看到：

✅ 依赖安装成功！

⚙️ 第二步：配置 Claude Code（2分钟）

2.1 找到 Claude Code 配置文件

Claude Code 的配置文件位于：

~/Library/Application Support/Claude/claude_desktop_config.json

2.2 方法一：使用命令行编辑（推荐）

在终端中运行以下命令：

# 创建配置文件目录（如果不存在）
mkdir -p ~/Library/Application\ Support/Claude

# 使用 nano 编辑器打开配置文件
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

2.3 添加 MCP 配置

如果文件是空的或不存在，完整复制以下内容：

{
  "mcpServers": {
    "funstat": {
      "command": "python3",
      "args": [
        "/Users/lucas/chat--1003255561049/funstat_mcp/server.py"
      ]
    }
  }
}

如果文件已经有内容，在 mcpServers 部分添加 "funstat" 配置：

{
  "mcpServers": {
    "现有的MCP服务器配置": {
      ...
    },
    "funstat": {
      "command": "python3",
      "args": [
        "/Users/lucas/chat--1003255561049/funstat_mcp/server.py"
      ]
    }
  }
}

2.4 保存并退出

如果使用 nano 编辑器：

按 Ctrl + O 保存
按 Enter 确认
按 Ctrl + X 退出

2.5 方法二：使用图形界面编辑（替代方案）

第 1 步：在 Finder 中打开配置目录

在终端中运行：

open ~/Library/Application\ Support/Claude

第 2 步：找到或创建 claude_desktop_config.json 文件

第 3 步：用文本编辑器打开，复制上面的配置内容

第 4 步：保存文件

2.6 验证配置文件格式

运行以下命令验证 JSON 格式是否正确：

python3 -c "import json; f=open(open('$HOME/Library/Application Support/Claude/claude_desktop_config.json')); json.load(f); print('✅ 配置文件格式正确！')"

如果格式错误，会显示具体的错误信息。

🔄 第三步：重启 Claude Code（30秒）

3.1 完全退出 Claude Code

方法 1: 右键点击 Dock 中的 Claude Code 图标 → 退出

方法 2: 在 Claude Code 中按 Cmd + Q

重要: 确保完全退出，而不是只关闭窗口！

3.2 重新启动 Claude Code

从应用程序文件夹或 Launchpad 启动 Claude Code

3.3 检查 MCP 服务器状态

启动后，在 Claude Code 中输入：

你好，请告诉我当前有哪些可用的 MCP 工具？

Claude 应该会列出包含 funstat_ 开头的工具，例如：

funstat_search
funstat_topchat
funstat_balance 等

✅ 第四步：测试功能（1分钟）

4.1 测试搜索功能

在 Claude Code 中输入：

帮我搜索 Python 相关的 Telegram 群组

预期响应：

Claude 会自动调用 funstat_search 工具，然后返回类似这样的结果：

我帮你搜索了 Python 相关的群组，找到以下结果：

1. ادوات بايثون • Python (152,441 成员)
2. Простой Python | Программирование (143,192 成员)
3. Learn Python (116,063 成员)
4. PythonNotes (109,769 成员)
5. Hacking Python Course Coding (100,134 成员)
...

这些群组都是关于 Python 编程学习和交流的，你想了解哪个群组的更多信息吗？

4.2 测试其他功能

试试这些命令：

查看热门群组：

获取热门 Telegram 群组列表

查询用户信息：

查询这个测试用户 ID: 7745296119

查看积分余额：

我的 funstat 积分还有多少？

搜索消息：

搜索包含 "GPT-4" 的 Telegram 消息

🎯 完整使用示例

示例 1：寻找技术交流群

你: "我想找一些关于 AI 和机器学习的技术交流群"

Claude: 我帮你搜索了 AI 和机器学习相关的群组：

【AI 相关群组】
1. AI Technology Discussion (500,000+ 成员)
   - 链接: https://t.me/...
   - 简介: AI 技术讨论...

2. Machine Learning 中文社区 (300,000+ 成员)
   - 链接: https://t.me/...
   - 简介: 机器学习中文交流...

【机器学习群组】
3. Deep Learning Researchers (200,000+ 成员)
   ...

你对哪个群组感兴趣？我可以帮你查看更详细的信息。

示例 2：批量查询

你: "帮我同时搜索这几个主题的群组：区块链、Web3、NFT"

Claude: [自动并行搜索三个关键词]

我已经为你搜索了三个主题，这里是结果汇总：

【区块链相关 - TOP 5】
1. Blockchain Technology (800,000 成员)
2. Crypto Trading 中文 (500,000 成员)
...

【Web3 相关 - TOP 5】
1. Web3 Developers (400,000 成员)
2. Decentralized Apps (300,000 成员)
...

【NFT 相关 - TOP 5】
1. NFT Marketplace (600,000 成员)
2. Digital Art Collectors (350,000 成员)
...

需要我提供更详细的信息吗？

示例 3：深度查询

你: "查询用户 @某个用户名 的详细信息"

Claude: [调用 funstat_user_info 工具]

用户信息：
- 用户名: @某个用户名
- 用户 ID: 123456789
- 注册时间: 2020-01-15
- 活跃状态: 活跃
- 加入的群组数: 50+
- 最近活跃: 2 天前

主要活跃群组：
1. Python 编程学习
2. AI 技术讨论
3. 区块链开发者社区
...

需要查看更多信息吗？

🔍 故障排除

问题 1：MCP 服务器未连接

症状: Claude Code 中看不到 funstat 相关工具

解决方案：

检查配置文件路径

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

应该看到包含 funstat 的配置

验证 server.py 文件存在

ls -l /Users/lucas/chat--1003255561049/funstat_mcp/server.py

验证 Python 可以运行

python3 /Users/lucas/chat--1003255561049/funstat_mcp/server.py --help

查看 Claude Code 日志
- 在 Claude Code 中按 Cmd + Option + I 打开开发者工具
- 查看 Console 标签
- 查找 funstat 或 MCP 相关的错误信息

问题 2：Session 文件错误

症状:

FileNotFoundError: Session 文件不存在

解决方案：

检查 session 文件是否存在

ls -l /Users/lucas/chat--1003255561049/funstat_mcp/funstat_bot_session.session

如果不存在，重新创建

cd /Users/lucas/chat--1003255561049
python3 create_session.py
cp funstat_bot_session.session funstat_mcp/

问题 3：依赖未安装

症状:

ModuleNotFoundError: No module named 'telethon'

解决方案：

cd /Users/lucas/chat--1003255561049/funstat_mcp
pip3 install -r requirements.txt

问题 4：响应超时

症状:

TimeoutError: 等待 BOT 响应超时

可能原因：

网络连接问题
Telegram 服务器繁忙
BOT 正在处理大量请求

解决方案：

检查网络连接
稍后重试
如果持续出现，增加超时时间（编辑 server.py）

问题 5：速率限制警告

症状:

INFO: 速率限制: 等待 0.5 秒

说明: 这是正常行为，不是错误！

MCP 服务器自动管理请求速率，确保不超过 Telegram 的限制（18请求/秒）。稍等片刻即可。

问题 6：配置文件格式错误

症状:

JSONDecodeError: Expecting property name enclosed in double quotes

解决方案：

使用在线 JSON 验证器检查格式
- 访问：https://jsonlint.com/
- 粘贴配置文件内容
- 检查错误提示
常见错误：
- 缺少逗号
- 多余的逗号
- 使用单引号而不是双引号
- 缺少闭合括号

正确格式示例：

{
  "mcpServers": {
    "funstat": {
      "command": "python3",
      "args": ["/Users/lucas/chat--1003255561049/funstat_mcp/server.py"]
    }
  }
}

📊 性能优化建议

1. 利用缓存

相同的查询在 1 小时内会直接从缓存返回，速度极快（<100ms）。

示例：

第一次: "搜索 Python 群组" → 1-2秒
第二次: "搜索 Python 群组" → <100ms（缓存）

2. 批量查询

可以在一次对话中要求 Claude 执行多个查询：

你: "帮我同时搜索：Python、JavaScript、Go 这三种编程语言的学习群组"

Claude: [自动并行执行三次搜索，整理结果]

3. 精确搜索

使用更具体的关键词可以获得更准确的结果：

❌ 不够精确: "编程" ✅ 更精确: "Python 机器学习" ✅ 最精确: "Python TensorFlow 深度学习"

🔐 安全最佳实践

1. Session 文件安全

⚠️ 重要: Session 文件相当于你的 Telegram 账号密码

保护措施：

# 设置严格的文件权限（只有你能读写）
chmod 600 /Users/lucas/chat--1003255561049/funstat_mcp/funstat_bot_session.session

检查权限：

ls -l /Users/lucas/chat--1003255561049/funstat_mcp/funstat_bot_session.session

应该看到：

-rw------- 1 lucas staff ... funstat_bot_session.session

2. 定期更换 Session

建议每 3-6 个月更换一次：

# 删除旧 session
rm /Users/lucas/chat--1003255561049/funstat_mcp/funstat_bot_session.session

# 创建新 session
cd /Users/lucas/chat--1003255561049
python3 create_session.py

# 复制到 MCP 目录
cp funstat_bot_session.session funstat_mcp/

# 重启 Claude Code

3. 使用独立账号

建议注册一个专门用于此项目的 Telegram 账号，不要使用主账号。

📈 高级配置

调整缓存时间

编辑 server.py，找到：

CACHE_TTL = 3600  # 默认 1 小时（秒）

修改为你需要的值：

CACHE_TTL = 7200  # 2 小时
# 或
CACHE_TTL = 1800  # 30 分钟

调整速率限制

编辑 server.py，找到：

RATE_LIMIT_PER_SECOND = 18  # 每秒最多 18 个请求

注意: 不建议提高此值，可能导致 Telegram 限流。

调整超时时间

编辑 server.py，在 send_command_and_wait 方法中：

async def send_command_and_wait(
    self,
    command: str,
    timeout: int = 10,  # 修改这里：10秒超时
    use_cache: bool = True
):

修改为：

timeout: int = 15,  # 15秒超时

🎓 学习资源

MCP 相关

MCP 官方文档: https://modelcontextprotocol.io/
Claude Code 文档: https://docs.anthropic.com/claude/docs

Telegram Bot API

Telegram Bot API: https://core.telegram.org/bots/api
Telethon 文档: https://docs.telethon.dev/

项目文档

本地文档: /Users/lucas/chat--1003255561049/funstat_mcp/README.md
MrDoc 文档: http://202.79.167.23:8081/project-89/

💡 使用技巧

技巧 1：组合查询

你: "帮我找 Python 和 AI 相关的群组，要求成员数超过 10 万"

Claude: [自动搜索并筛选]

技巧 2：定期查询

你: "每周帮我查一次我的 funstat 积分余额"

Claude: [可以设置提醒或定期查询]

技巧 3：数据分析

你: "分析一下最近区块链领域最活跃的 10 个群组"

Claude: [搜索并分析数据]

📞 获取帮助

自助诊断

运行测试脚本：

cd /Users/lucas/chat--1003255561049/funstat_mcp
python3 test_server.py

查看日志

# 查看最近的日志
tail -f ~/.claude_code/logs/mcp.log

联系支持

查看文档: http://202.79.167.23:8081/project-89/doc-392/
GitHub Issues: (如果有的话)

✅ 快速检查清单

在使用前，确保：

Python 3.10+ 已安装
依赖已安装（pip3 install -r requirements.txt）
Session 文件存在且有正确权限
Claude Code 配置文件已正确修改
Claude Code 已完全重启
测试查询成功

🎉 恭喜！

如果你完成了以上所有步骤，你现在已经可以：

✅ 通过自然语言查询 10 亿+ Telegram 用户数据 ✅ 搜索群组、频道、用户 ✅ 分析 Telegram 社区趋势 ✅ 自动化 Telegram 数据收集

开始探索吧！ 🚀

文档版本: 1.0 最后更新: 2025-10-26 适用于: macOS, Claude Code, Funstat MCP Server v1.0

14 KiB Raw Permalink Blame History Unescape Escape

Funstat MCP Server - 快速开始教程

📋 前置要求检查

检查 Python 版本

🚀 第一步：安装依赖（2分钟）

1.1 打开终端

1.2 进入项目目录

1.3 安装 Python 依赖

1.4 验证安装

⚙️ 第二步：配置 Claude Code（2分钟）

2.1 找到 Claude Code 配置文件

2.2 方法一：使用命令行编辑（推荐）

2.3 添加 MCP 配置

2.4 保存并退出

2.5 方法二：使用图形界面编辑（替代方案）

2.6 验证配置文件格式

🔄 第三步：重启 Claude Code（30秒）

3.1 完全退出 Claude Code

3.2 重新启动 Claude Code

3.3 检查 MCP 服务器状态

✅ 第四步：测试功能（1分钟）

4.1 测试搜索功能

4.2 测试其他功能

🎯 完整使用示例

示例 1：寻找技术交流群

示例 2：批量查询

示例 3：深度查询

🔍 故障排除

问题 1：MCP 服务器未连接

问题 2：Session 文件错误

问题 3：依赖未安装

问题 4：响应超时

问题 5：速率限制警告

问题 6：配置文件格式错误

📊 性能优化建议

1. 利用缓存

2. 批量查询

3. 精确搜索

🔐 安全最佳实践

1. Session 文件安全

2. 定期更换 Session

3. 使用独立账号

📈 高级配置

调整缓存时间

调整速率限制

调整超时时间

🎓 学习资源

MCP 相关

Telegram Bot API

项目文档

💡 使用技巧

技巧 1：组合查询

技巧 2：定期查询

技巧 3：数据分析

📞 获取帮助

自助诊断

查看日志

联系支持

✅ 快速检查清单

🎉 恭喜！

14 KiB

Raw Permalink Blame History