内容
<p align="center">
<img src="https://raw.githubusercontent.com/Mihailo2501/potter-mcp/main/assets/logo.png" width="120" alt="Potter logo" />
</p>
<h1 align="center">波特</h1>
<p align="center">
作为Claude Code的MCP的GTM研究工具。开源，BYOK，无托管层。
</p>
<p align="center">
<a href="https://www.npmjs.com/package/potter-mcp"><img src="https://img.shields.io/npm/v/potter-mcp.svg" alt="npm" /></a>
<a href="https://github.com/Mihailo2501/potter-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js" /></a>
<a href="https://github.com/Mihailo2501/potter-mcp/actions"><img src="https://github.com/Mihailo2501/potter-mcp/actions/workflows/test.yml/badge.svg" alt="CI" /></a>
</p>
---
## 它是什么
安装波特和Claude Code，获取21种B2B研究工具：LinkedIn个人资料/公司/帖子查找，网页抓取和搜索，浏览器自动化基元，以及五个跨提供商的复合工具。
推理运行在您现有的Claude订阅（Pro或Max）上。为Apify、Firecrawl和Browserbase提供您自己的密钥。直接向提供商付费。无需计费，无需身份验证，无需托管层。MIT。
## 快速安装
```bash
claude mcp add potter --scope user -- npx -y potter-mcp
```
然后编辑 `~/.claude.json`下的 `mcpServers`以添加您的提供商密钥：
```json
"potter": {
"command": "npx",
"args": ["-y", "potter-mcp"],
"env": {
"POTTER_APIFY_TOKEN": "apify_api_xxx",
"POTTER_FIRECRAWL_API_KEY": "fc-xxx",
"POTTER_BROWSERBASE_API_KEY": "bb_live_xxx",
"POTTER_BROWSERBASE_PROJECT_ID": "xxx"
}
}
```
`npx -y`在每个Claude Code会话启动时自动拉取最新的发布版本；无需全局安装。
对于本地模式下的浏览器工具，一次性执行：`npx playwright install chromium`。重启Claude Code。
## 试用
在Claude Code中：
- "研究这个人：https://www.linkedin.com/in/satyanadella/"
- "为我找到Vercel的平台工程负责人"
- "Linear是否正在招聘后端工程师？linear.app"
- "以JSON格式提取https://www.anthropic.com/pricing的定价计划"
21个示例提示位于 [examples/](https://github.com/Mihailo2501/potter-mcp/tree/main/examples)。
## 工具箱（21种工具）
**复合工具（5）** （一个调用跨多个提供商）：
- `potter_research_person`：个人资料 + 帖子 + 当前公司 + 新闻
- `potter_research_company`：LinkedIn页面 + 6个网站页面 + 新闻，可选 `focus` 偏差
- `potter_summarize_linkedin_posts`：帖子 + tf-idf主题 + 值得注意的引用
- `potter_find_decision_maker`：公司 + 员工 + token-overlap评分
- `potter_extract_structured`：Firecrawl JSON格式提取，带有深度限制的模式
**LinkedIn基元（3）：** `potter_linkedin_profile`，`potter_linkedin_company`，`potter_linkedin_posts`。
**网页基元（3）：** `potter_web_scrape`，`potter_web_search`，`potter_web_crawl`。
**浏览器（9）：** `potter_browser_open`，`_click`，`_fill`，`_scroll`，`_extract`，`_inspect_styles`，`_screenshot`，`_close`，`_act`（实验性，由 `POTTER_ENABLE_EXPERIMENTAL_BROWSER_ACT` 控制）。
**实用工具（1）：** `potter_provider_status`：验证提供商密钥，可选地进行实时API调用。
完整参考资料位于 [docs/tools.md](https://github.com/Mihailo2501/potter-mcp/blob/main/docs/tools.md)。
## 提供商栈
| 提供商 | 波特调用它用于 | 注册 |
|---|---|---|
| Apify | LinkedIn个人资料/公司/帖子/员工（ `docs/provider-benchmarks.md`中的执行器选择） | https://apify.com |
| Firecrawl | 网页抓取/搜索/爬取/结构化提取 | https://firecrawl.dev |
| Browserbase | 由Stagehand管理的浏览器会话（本地Playwright的替代方案） | https://browserbase.com |
| Anthropic | 本地模式下自然语言浏览器操作所需的 | https://console.anthropic.com |
| OpenAI | 本地模式下自然语言浏览器操作的替代LLM | https://platform.openai.com |
所有提供商都针对您自己的账户积分进行收费；波特不收取任何费用。免费/付费层级各不相同；请查看每个提供商的当前定价页面。
**必需：** Apify + Firecrawl。 **浏览器工具必需：** Browserbase 或本地 Playwright。 **自然语言浏览器操作必需** （`potter_browser_click`，`potter_browser_fill`，`potter_browser_extract`带有指令，`potter_browser_scroll`带有 `to_selector`，以及 `potter_browser_act`）：Browserbase（捆绑LLM）或本地 Anthropic/OpenAI 密钥。其他浏览器基元（`open`，`direction`仅限 `scroll`，`inspect_styles`，`screenshot`，`close`）无需任何LLM即可工作。
## Apify执行器覆盖
波特自带基准测试默认值（参见 `docs/provider-benchmarks.md`）。如果执行器损坏或您想要不同的执行器，请通过环境变量覆盖：
```bash
POTTER_APIFY_LINKEDIN_PROFILE_ACTOR=apimaestro/linkedin-profile-batch-scraper-no-cookies-required
POTTER_APIFY_LINKEDIN_COMPANY_ACTOR=apimaestro/linkedin-company-detail
POTTER_APIFY_LINKEDIN_POSTS_ACTOR=apimaestro/linkedin-batch-profile-posts-scraper
# 默认已存在；如果您处于Apify付费计划并且想要更丰富的每位员工数据，请覆盖为harvestapi
POTTER_APIFY_LINKEDIN_EMPLOYEES_ACTOR_INTERNAL=harvestapi/linkedin-company-employees
```
波特为每个执行器都有一个硬编码的标准化器；如果您覆盖为我们没有标准化器的执行器，则工具返回一个结构化错误，指向 `src/providers/apify-actors.ts`以添加一个。
**关于 `find_decision_maker` 的说明：** 默认的 `apimaestro` 员工执行器按结果付费，无订阅，因此它适用于免费的Apify 5美元注册积分（~20次运行）。 替代的 `harvestapi` 员工执行器返回更丰富的每位员工数据，但对免费Apify用户有10次运行限制，之后需要Apify Starter计划（49美元/月）。 有关完整理由，请参见 `docs/provider-benchmarks.md`。
## 可接受的使用
波特用于合法的B2B研究：寻找潜在客户、账户情报、候选人研究、市场研究、竞争分析。 不用于：
- 大规模冷 outreach 自动化
- 大规模抓取个人信息用于重新分发
- 自动化LinkedIn操作（连接请求、消息、评论垃圾邮件）
您负责遵守波特集成的每个第三方提供商的服务条款（Apify、Firecrawl、Browserbase、LinkedIn、Anthropic、OpenAI）。 浏览器工具（`potter_browser_*`）主动拒绝 `linkedin.com`上的任何URL或活动页面；请改用LinkedIn基元。
波特不存储任何内容。 每次调用都是直接传递到您配置的提供商，使用您自己的密钥。 日志仅输出到stderr，并通过一个重构层，该层在写入前屏蔽任何配置的令牌值。 无需遥测，无需分析，无需提供商以外的远程调用。
## LinkedIn操作说明
波特不直接抓取LinkedIn。 它使用您自己的API密钥调用第三方数据提供商（Apify Harvest，Apimaestro）。 这些提供商运行自己的抓取基础设施，并吸收LinkedIn侧的风险。
对于高容量使用，请从专用机器或VPN运行波特。 在您的网络上，正常的IP下进行大量LinkedIn调用可能会触发LinkedIn的反自动化机制，从而影响您的帐户。
## 配置参考
所有波特环境变量的前缀均为 `POTTER_`。 `.env.example`中列出了完整列表。 关键变量：
- `POTTER_APIFY_TOKEN`，`POTTER_FIRECRAWL_API_KEY`：LinkedIn + 网页工具所需。
- `POTTER_BROWSERBASE_API_KEY` + `POTTER_BROWSERBASE_PROJECT_ID`：浏览器工具所需（或回退到本地Playwright）。
- `POTTER_ANTHROPIC_API_KEY` / `POTTER_OPENAI_API_KEY`：可选，仅用于 `potter_browser_act` 在Browserbase不可用时的LLM备用。
- `POTTER_MAX_RESPONSE_BYTES=20000`：响应上限（建议不要提高；Claude Code的上下文成本增长迅速）。
- `POTTER_CONCURRENCY_LIMIT=5`：提供商调用并发数。
- `POTTER_BROWSER_SESSION_TIMEOUT_MINUTES=10`：浏览器会话空闲超时。
- `POTTER_ENABLE_EXPERIMENTAL_BROWSER_ACT=true`：启用LLM驱动的 `potter_browser_act` （v1中实验性）。
- `POTTER_ENABLE_PING=false`：`potter_ping` 健康检查，默认关闭以匹配锁定的21工具界面。
## 故障排除
参见 [docs/troubleshooting.md](https://github.com/Mihailo2501/potter-mcp/blob/main/docs/troubleshooting.md)，解决：Playwright安装失败、Linux上的libnss3、Node版本不匹配、卡住的浏览器会话、工具选择失误、部分失败的信封形状。
## 贡献
参见 [CONTRIBUTING.md](https://github.com/Mihailo2501/potter-mcp/blob/main/CONTRIBUTING.md)。 由一人维护，业余时间维护。 欢迎修复bug、提供适配器PR、文档和示例提示。 新工具或复合工具需先讨论（开启问题），以便保持界面一致。
## 安全和数据处理
波特不存储任何内容。 每次请求直接传递给使用您自己的密钥配置的提供商。 日志仅输出到stderr，并通过一个重构层，该层在写入前屏蔽任何配置的令牌值。 无需遥测，无需分析，无需提供商以外的远程调用。
## 致谢
感谢Brandon Guerrero，我的Clay Bootcamp导师，他鼓励我构建这个。
## 许可证
MIT。 参见 [LICENSE](https://github.com/Mihailo2501/potter-mcp/blob/main/LICENSE)。
