内容
# nitter-mcp
`nitter-mcp` 是一个模型上下文协议（MCP）服务器，它从 Nitter 实例读取数据并返回规范化的 JSON，支持：
- 推文搜索（RSS 端点）
- 用户动态（RSS 端点）
- 用户搜索（HTML 端点）
## 功能特点
- 严格的 `zod` 模式用于 MCP 工具输入和输出
- 规范化、适合大型语言模型的 JSON 载荷
- URL 重写，从 Nitter 本地链接到 `https://x.com/...`
- 明确的速率限制和上游错误分类
- 通过环境变量选择传输方式（`stdio` 或独立 HTTP）
- 可流式传输的 HTTP 端点，兼容可选的废弃 SSE 端点
- 回归脚本，启动服务器并通过 MCP 标准输入调用工具
## 要求
- Node.js `>=18.17`
- Yarn `1.x`
## 快速开始
### 标准输入模式（默认）
```bash
yarn install
yarn build
yarn start
```
本地开发：
```bash
yarn dev
```
### 独立 HTTP 模式
```bash
yarn install
yarn build
yarn start:http
```
本地开发：
```bash
yarn dev:http
```
## 配置
环境变量：
- `NITTER_BASE_URL`（可选）：Nitter 服务器基准 URL
- 默认：`https://nitter.net`
- `MCP_TRANSPORT`（可选）：`stdio`（默认）或 `http`
- `MCP_HOST`（可选，HTTP 模式）：绑定主机地址
- 默认：`127.0.0.1`
- `MCP_PORT`（可选，HTTP 模式）：服务器端口
- 默认：`3000`
- `MCP_HTTP_PATH`（可选，HTTP 模式）：可流式传输的 HTTP MCP 端点路径
- 默认：`/mcp`
- `MCP_ENABLE_SSE_COMPAT`（可选，HTTP 模式）：启用废弃的 HTTP + SSE 兼容性
- 默认：`true`
- `MCP_SSE_PATH`（可选，HTTP 模式）：废弃的 SSE 流端点路径
- 默认：`/sse`
- `MCP_SSE_MESSAGES_PATH`（可选，HTTP 模式）：废弃的 SSE 消息端点路径
- 默认：`/messages`
### `.env` 支持和推荐设置
`nitter-mcp` 从 `process.env` 读取环境变量。
- `.env` **不是必需的**
- `.env` **不会被此软件包自动加载**
- 环境值通常由 MCP 主机、Shell 或进程启动器提供
设置 `NITTER_*` 的推荐方法：
1. 在 MCP 服务器配置中（适用于 Cursor/VS Code），使用服务器 `env` 块。
2. 在 Shell 中进行本地运行，导出后启动：
```bash
export NITTER_BASE_URL="https://nitter.net"
yarn start
```
3. 一次性命令：
```bash
NITTER_BASE_URL="https://nitter.net" yarn start
```
如果您更喜欢使用 `.env` 文件工作流，请在您自己的设置中使用任何外部加载器/工具，并在启动 `nitter-mcp` 时填充这些环境变量。
URL 重写始终递归应用于工具响应中的 URL：
- `${NITTER_BASE_URL}/...` -> `https://x.com/...`
- `https://localhost/...` -> `https://x.com/...`
- `http://localhost/...` -> `https://x.com/...`
## 工具
### `nitter_search_tweets`
通过 `/search/rss?f=tweets` 搜索推文。
输入：
- `query: string`（必需）
- `since?: "YYYY-MM-DD"`
- `until?: "YYYY-MM-DD"`
- `minFaves?: number`（映射到 `min_faves`）
- `include?: SearchFilters`（映射到 `f-*` 查询参数，值为 `on`）
- `exclude?: SearchFilters`（映射到 `e-*` 查询参数，值为 `on`）
`SearchFilters` 键：
- `nativeRetweets`
- `media`
- `videos`
- `news`
- `nativeVideo`
- `replies`
- `links`
- `images`
- `quote`
- `spaces`
### `nitter_feed_user`
通过 `/{username}/rss` 获取用户的 RSS 动态。
输入：
- `username: string`（必需）
### `nitter_search_users`
通过 `/search?f=users&q=...` 搜索用户，并从 Nitter HTML 解析用户卡片。
输入：
- `query: string`（必需）
- `cursor?: string`（分页游标）
## 错误处理
工具返回 MCP 错误响应（`isError: true`），具有结构化的有效载荷：
- `RATE_LIMITED`
- 包括 `statusCode`、`retryable: true`、可选的 `retryAfterSeconds` 和 `snippet`
- `UPSTREAM_ERROR`
- 包括 `statusCode`、`retryable`（对于 `5xx` 为 `true`）和 `snippet`
- `INVALID_PAYLOAD`
- 当检测到预期的 RSS/HTML 有效载荷形状时返回
速率限制检测包括直接的 HTTP `429` 和 Nitter 响应中的常见速率限制短语。
## 回归检查
运行一个命令进行标准输入回归检查（启动服务器 + MCP 客户端调用）：
```bash
yarn regression
```
运行 HTTP + SSE 兼容性回归检查：
```bash
yarn regression:http
```
回归的选项环境变量：
- `NITTER_BASE_URL`
- `NITTER_TEST_QUERY`
- `NITTER_TEST_USERNAME`
- `MCP_HOST`
- `MCP_PORT`
- `MCP_HTTP_PATH`
- `MCP_SSE_PATH`
`yarn regression` 将 `RATE_LIMITED`、`UPSTREAM_ERROR` 和 `INVALID_PAYLOAD` 视为非致命警告（在公共 Nitter 实例上很常见），并仍然验证工具注册和 MCP 传输行为。
`yarn regression:http` 应用相同的非致命处理，同时验证可流式传输的 HTTP 和废弃的 SSE 兼容性端点。
## MCP 配置示例（Cursor/VS Code）
标准输入模式（默认）：
```json
{
"mcp": {
"servers": {
"nitter": {
"command": "node",
"args": ["/absolute/path/to/nitter-mcp/dist/index.js"],
"env": {
"NITTER_BASE_URL": "https://nitter.net"
}
}
}
}
}
```
通过流式 HTTP 连接到独立服务器（推荐）：
```json
{
"mcp": {
"servers": {
"nitter-remote": {
"url": "http://127.0.0.1:3000/mcp"
}
}
}
}
```
通过废弃的 HTTP + SSE 兼容性连接到独立服务器：
```json
{
"mcp": {
"servers": {
"nitter-remote-sse": {
"transport": "sse",
"url": "http://127.0.0.1:3000/sse"
}
}
}
}
```
## 运行独立 MCP 服务器
以独立的 HTTP MCP 服务器运行 `nitter-mcp`：
```bash
MCP_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=3000 yarn start
```
您也可以使用脚本快捷方式：
```bash
yarn start:http
```
常见的运行时环境变量：
- `MCP_TRANSPORT=http`
- `MCP_HOST`（默认 `127.0.0.1`）
- `MCP_PORT`（默认 `3000`）
- `MCP_HTTP_PATH`（默认 `/mcp`）
- `MCP_ENABLE_SSE_COMPAT`（默认 `true`）
- `MCP_SSE_PATH`（默认 `/sse`）
- `MCP_SSE_MESSAGES_PATH`（默认 `/messages`）
- `NITTER_BASE_URL`（默认 `https://nitter.net`）
运行时，客户端可以连接：
- 流式 HTTP：`http://127.0.0.1:3000/mcp`
- 废弃的 SSE 流：`http://127.0.0.1:3000/sse`
- 废弃的 SSE 消息：`http://127.0.0.1:3000/messages?sessionId=<id>`
您可以将更多变量添加到此 `env` 块中。
`nitter-mcp` 消耗 `NITTER_BASE_URL` 以及上述 `MCP_*` 传输/运行时变量。
`NITTER_TEST_QUERY` 和 `NITTER_TEST_USERNAME` 用于回归脚本，而不是正常的 MCP 服务器运行时。
