内容
# @riseup-oss/mcp
官方 [MCP](https://modelcontextprotocol.io) 服务器，适用于 [RiseUp](https://riseup.co.il) — 通过 Claude Desktop、Base44、Claude Agent SDK 等 MCP 客户端以编程方式只读访问您自己的现金流数据。
> **状态：** v0.1。该软件包通过 RiseUp API 返回真实数据。
## 您可以用它做什么
安装和配置完成后，向您的 AI 助手提问，例如：
- "这个月的 RiseUp 预算是多少？"
- "显示我 2026 年 5 月的预算。"
- "将我的预算与上个月进行比较。"
助手调用 `get_budget` 工具，该工具使用您创建的个人访问令牌（PAT）通过 RiseUp 的公开 API 获取您的实际现金流数据。
## 安装
```bash
npm install -g @riseup-oss/mcp
```
需要 Node.js 18+。
## 设置
### 1. 创建个人访问令牌
访问 RiseUp 的[开发者令牌页面](https://input.riseup.co.il/developer/tokens)，创建令牌，选择 `budget:read` 范围，然后复制它。**它只显示一次。**
令牌类似于 `riseup_pat_<32-bytes-base64url>`。
### 2. 配置您的 MCP 客户端
#### Claude Desktop
添加到您的 `claude_desktop_config.json`（在 macOS 上为 `~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"riseup": {
"command": "npx",
"args": ["-y", "@riseup-oss/mcp"],
"env": {
"RISEUP_PAT": "riseup_pat_粘贴您的令牌"
}
}
}
}
```
**完全退出 Claude Desktop（在 macOS 上为 Cmd+Q）并重新打开** — 关闭窗口是不够的。Claude Desktop 仅在启动时读取 `claude_desktop_config.json，因此对 `RISEUP_PAT` 或其他环境值的任何更改都需要完全重启才能生效。重启后，`get_budget` 工具应该出现。
#### Claude Agent SDK
```typescript
import { Claude } from '@anthropic-ai/claude-agent-sdk';
const claude = new Claude({
mcpServers: {
riseup: {
command: 'npx',
args: ['-y', '@riseup-oss/mcp'],
env: { RISEUP_PAT: process.env.RISEUP_PAT },
},
},
});
```
## 环境变量
| 变量 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|
| `RISEUP_PAT` | 是 | — | 您的 `riseup_pat_…` 个人访问令牌 |
| `RISEUP_API_BASE` | 否 | `https://input.riseup.co.il` | 用于暂存/开发环境的覆盖 |
## 工具（v0.1）
| 工具 | 所需范围 | 描述 |
|---|---|---|
| `get_budget` | `budget:read` | 获取给定月份的客户预算。接受 `YYYY-MM`、`current` 或 `previous`。 |
更多工具（`get_transactions`、`get_balances`、`get_cashflow`）将在 v0.2+ 中推出。
## 文档
更详细的文档位于 [`docs/`](./docs)：
- [快速入门](./docs/quickstart.md) — 五分钟内完成第一个 API 调用
- [身份验证](./docs/authentication.md) — 令牌格式、头部、撤销、`X-Riseup-Token-Ref` 相关性头部
- [速率限制](./docs/rate-limits.md) — 限制、`429` 形状、如何处理
- [错误](./docs/errors.md) — 完整的错误目录
- [预算参考](./docs/reference/budget.md) — 三个预算端点的详细信息
## 安全
- PAT 仅存在于您的本地 MCP 客户端配置中 — 它**永远不会**发送到 Anthropic 或任何第三方。MCP 服务器在您的机器上运行；它只与 RiseUp API 和您的本地 MCP 客户端通信。
- 令牌是只读的。它无法更改您的帐户。
- 令牌默认 30 天后过期。在 `/developer/tokens` 处随时撤销令牌。
- 永远不要分享您的令牌，粘贴到聊天中，或提交到源代码控制中。
## 开发
```bash
git clone git@github.com:riseup-oss/mcp.git
cd mcp
npm install
npm run build
npm test
```
### 本地烟雾测试
`examples/smoke-test.mjs` 驱动内置的 MCP 服务器作为一个真正的 MCP 客户端（与 Claude Desktop 使用的相同 `@modelcontextprotocol/sdk` stdio 传输），调用 `get_budget`，并打印关于响应的 PII 安全形状信号 — 对于在不将 LLM 引入循环的情况下验证端到端管道（PAT → RiseUp API → 返回）非常有用：
```bash
RISEUP_PAT=riseup_pat_... RISEUP_API_BASE=http://127.0.0.1:6040 \
node examples/smoke-test.mjs --date=current
```
`examples/fetch-budget.mjs` 是一个较低级别的替代方案，它直接调用 HTTP 端点并将 JSON 正文转储到 stdout 以进行本地检查：
```bash
RISEUP_PAT=riseup_pat_... node examples/fetch-budget.mjs 2026-05 > /tmp/budget.json
```
两者默认 `RISEUP_API_BASE` 为 `http://127.0.0.1:6040`，因为 Node 18 的 `fetch` 解析 `localhost` 为 `::1`，而大多数服务器仅绑定 IPv4 — 如果您的本地 API 服务器在其他地方，请显式设置。
## 许可证
MIT
