内容
# Investec OpenAPI MCP 服务器
[](https://github.com/Investec-Developer-Community/investec-mcp-server/actions)
[](https://opensource.org/licenses/MIT)
[](https://developer.investec.com/)
[](https://modelcontextprotocol.io/)
一款高级、生产就绪的 **模型上下文协议（MCP）服务器**，封装了官方的Investec OpenAPI。它使AI编码助手、开发人员代理（例如Claude Desktop、Cursor或自定义MCP客户端）和自动化脚本能够直接、安全地与您的Investec个人、商业、公司和可编程卡账户进行交互。
```
██╗███╗ ██╗██╗ ██╗███████╗███████╗████████╗███████╗ ██████╗
██║████╗ ██║██║ ██║██╔════╝██╔════╝╚══██╔══╝██╔════╝██╔════╝
██║██╔██╗ ██║██║ ██║█████╗ ███████╗ ██║ █████╗ ██║
██║██║╚██╗██║╚██╗ ██╔╝██╔══╝ ╚════██║ ██║ ██╔══╝ ██║
██║██║ ╚████║ ╚████╔╝ ███████╗███████║ ██║ ███████╗╚██████╗
╚═╝╚═╝ ╚═══╝ ╚═══╝ ╚══════╝╚══════╝ ╚═╝ ╚══════╝ ╚═════╝
OPENAPI MCP SERVER
```
---
## 关键架构亮点
* **🔒 安全的内存令牌管理**：自动执行OAuth2客户端凭证流，安全地缓存令牌，并在令牌过期之前主动刷新令牌。**永远不会将令牌或机密写入磁盘或打印到终端日志中。**
* **🔌 零配置沙盒模式**：使用官方Investec公共沙盒凭证开箱即用。您可以立即测试账户余额、付款、报表和交易列表，无需先注册开发人员账户。
* **🛠️ 强大的类型定义**：为所有API模型（包括复杂的数据包，如批量付款（`paymultiple`）和可编程卡代码编译）公开严格的TypeScript类型定义。
* **🚀 标准输入/输出传输协议**：在标准I/O（stdio）上实现JSON-RPC 2.0，符合官方模型上下文协议（MCP）规范。
---
## 仓库结构
```
investec-mcp-server/
├── .github/workflows/ci.yml # 自动CI验证管道
├── dist/ # 编译的JavaScript构建输出
├── examples/ # 独立的SDK演示代码
│ └── pb-demo.ts # InvestecClient独立使用的演示
├── src/ # TypeScript源代码
│ ├── index.ts # MCP服务器声明和工具路由器
│ ├── investec-client.ts # 核心HTTP客户端和令牌管理器
│ └── types.ts # 严格的TypeScript API模式
├── .env.example # 配置设置模板
├── CONTRIBUTING.md # 开源贡献指南
├── LICENSE # 开源MIT许可证
├── package.json # 构建依赖和命令
└── tsconfig.json # TypeScript编译规则
```
---
## 安装和设置
### 1. 从源代码构建
确保您的系统已安装 **Node.js**（v18.0.0或更高版本）。
```bash
# 克隆仓库
git clone https://github.com/Investec-Developer-Community/investec-mcp-server.git
cd investec-mcp-server
# 安装软件包依赖
npm install
# 将TypeScript编译为JavaScript
npm run build
```
### 2. 验证连接（沙盒模式）
运行沙盒集成测试套件，以验证服务器是否连接到Investec开发人员沙盒API，获取模拟账户，并读取资产负债表：
```bash
npm run test-sandbox
```
---
## 环境配置
默认情况下，服务器在`sandbox`模式下运行。要连接到您的实时银行数据，请在项目根目录中创建`.env`文件（或复制`.env.example`到`.env`）：
```ini
# 'production' 访问实时数据，或 'sandbox' 用于模拟账户
INVESTEC_ENVIRONMENT=production
# 您的Investec开发人员凭证（从Investec Online获取）
INVESTEC_CLIENT_ID=your_client_id
INVESTEC_CLIENT_SECRET=your_client_secret
INVESTEC_API_KEY=your_api_key
# 可选：Advisor或中介API范围所需
INVESTEC_INTERMEDIARY_ID=your_intermediary_id
```
> [!CAUTION]
> **保护您的凭证！** 永远不要将您的`.env`文件提交到公共版本控制中。已预配置的`.gitignore`阻止了`.env`上传。
---
## Claude Desktop集成
要将MCP服务器链接到您的本地 **Claude Desktop** 应用程序，请编辑您的 `claude_desktop_config.json`：
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
在 `mcpServers` 下添加服务器规范：
```json
{
"mcpServers": {
"investec-banking": {
"command": "node",
"args": [
"C:/path/to/investec-mcp-server/dist/index.js"
]
}
}
}
```
*注意：确保将 `C:/path/to/investec-mcp-server` 替换为您的本地项目目录的绝对路径。*
---
## 独立SDK用法
您还可以将底层的 `InvestecClient` 类作为独立的SDK导入并在您自己的自定义Node.js项目中使用，与MCP协议无关：
```typescript
import { InvestecClient } from "./src/investec-client";
async function main() {
// 使用.env变量或回退到公共沙盒默认值
const client = new InvestecClient({ environment: "sandbox" });
// 列出账户
const response = await client.pbListAccounts();
const accounts = response.data.accounts;
console.log(`找到 ${accounts.length} 个账户。`);
}
main();
```
*有关完整的代码演示，请参阅 [examples/pb-demo.ts](file:///c:/Users/jonel/Downloads/MCP_SERVER/examples/pb-demo.ts)。*
---
## 暴露的工具参考
服务器注册了以下MCP工具：
### 私人银行（PB）
| 工具名称 | 参数 | 描述 |
|---|---|---|
| `investec_pb_list_accounts` | 无 | 列出关联账户（支票账户、储蓄账户、个人资料）。 |
| `investec_pb_get_account_balance` | `accountId` | 获取可用余额、当前余额和货币余额详情。 |
| `investec_pb_get_account_transactions` | `accountId`, `fromDate?`, `toDate?`, `transactionType?`, `includePending?` | 获取筛选后的交易流水。 |
| `investec_pb_get_pending_transactions` | `accountId` | 列出未完成的待处理交易（例如刷卡交易）。 |
| `investec_pb_list_profiles` | 无 | 列出与用户身份关联的在线个人资料。 |
| `investec_pb_list_profile_accounts` | `profileId` | 列出与特定个人资料关联的账户。 |
| `investec_pb_list_beneficiaries` | 无 | 获取已注册的付款受益人。 |
| `investec_pb_pay_multiple` | `accountId`, `paymentList` | 向受益人列表进行批量付款。 |
| `investec_pb_transfer_multiple` | `accountId`, `paymentList` | 在自己的账户之间转移资金。 |
| `investec_pb_get_documents` | `accountId`, `fromDate?`, `toDate?` | 检索报表和税务证书列表。 |
| `investec_pb_get_document` | `accountId`, `documentType`, `documentDate` | 获取特定报表PDF的下载链接。 |
### 可编程卡
| 工具名称 | 参数 | 描述 |
|---|---|---|
| `investec_card_list_cards` | 无 | 列出与账户关联的信用卡和借记卡。 |
| `investec_card_create_virtual_card` | `accountNumber`, `embossName`, `embossName2?` | 动态创建虚拟卡。 |
| `investec_card_get_code` | `cardKey` | 获取草稿/工作卡JS脚本。 |
| `investec_card_update_code` | `cardKey`, `code` | 上传可编程卡的新代码草稿。 |
| `investec_card_publish_code` | `cardKey` | 发布并激活卡刷授权的代码。 |
| `investec_card_execute_code` | `cardKey`, `authorizationModel` | 模拟卡刷以测试自定义脚本逻辑。 |
| `investec_card_get_execution_history`| `cardKey` | 获取脚本的执行历史日志。 |
| `investec_card_get_env_vars` | `cardKey` | 检索脚本环境机密。 |
| `investec_card_update_env_vars` | `cardKey`, `variables` | 更新脚本密钥-值环境机密。 |
| `investec_card_toggle_programmable` | `cardKey` | 开启或关闭可编程功能。 |
### 企业和机构银行（CIB）
| 工具名称 | 参数 | 描述 |
|---|---|---|
| `investec_cib_list_accounts` | 无 | 列出企业账户。 |
| `investec_cib_get_account_transactions`| `accountId`, `fromDate?`, `toDate?`, `page?` | 获取具有分页的企业交易流水。 |
| `investec_cib_list_companies` | 无 | 列出个人资料下的公司实体。 |
| `investec_cib_get_orders_shipments_report` | `companyName` | 查询当前货物和订单状态数据。 |
---
## 许可证
该项目是开源的，基于 [MIT License](LICENSE) 发布。
您可以自由地fork、分发和集成该项目到商业和私人设置中。
有关官方API支持，请咨询 [Investec Developer Portal](https://developer.investec.com)。
