🔵 Investec OpenAPI MCP Server

A premium, production-ready Model Context Protocol (MCP) server that wraps the official Investec OpenAPI. It enables AI coding assistants, developer agents (such as Claude Desktop, Cursor, or custom MCP clients), and automation scripts to interact directly and securely with your Investec personal, business, corporate, and programmable card accounts.

██╗███╗   ██╗██╗   ██╗███████╗███████╗████████╗███████╗ ██████╗ 
██║████╗  ██║██║   ██║██╔════╝██╔════╝╚══██╔══╝██╔════╝██╔════╝ 
██║██╔██╗ ██║██║   ██║█████╗  ███████╗   ██║   █████╗  ██║      
██║██║╚██╗██║╚██╗ ██╔╝██╔══╝  ╚════██║   ██║   ██╔══╝  ██║      
██║██║ ╚████║ ╚████╔╝ ███████╗███████║   ██║   ███████╗╚██████╗ 
╚═╝╚═╝  ╚═══╝  ╚═══╝  ╚══════╝╚══════╝   ╚═╝   ╚══════╝ ╚═════╝ 
                      OPENAPI MCP SERVER

---

🌟 Key Architecture Highlights

• 🔒 Secure In-Memory Token Management: Automatically performs the OAuth2 Client Credentials flow, safely caches tokens, and auto-refreshes them proactively before expiration. No tokens or secrets are ever written to disk or printed in terminal logs.
• 🔌 Zero-Config Sandbox Mode: Connects out-of-the-box using the official Investec public Sandbox credentials. You can test account balances, payments, statements, and transaction listings instantly without registering for an developer account first.
• 🛠️ Robust Typings: Exposes strict TypeScript type definitions for all API models, including complex payloads like batch payments (paymultiple) and programmable card code compilation.
• 🚀 Stdio Transport Protocol: Implements JSON-RPC 2.0 over standard I/O (stdio) compliant with the official Model Context Protocol (MCP) specifications.

---

📂 Repository Structure

investec-mcp-server/
├── .github/workflows/ci.yml # Automated CI validation pipeline
├── dist/                    # Compiled JavaScript build outputs
├── examples/                # Standalone SDK demo code
│   └── pb-demo.ts           # Demo of InvestecClient standalone usage
├── src/                     # TypeScript source code
│   ├── index.ts             # MCP server declaration and tools router
│   ├── investec-client.ts   # Core HTTP client & token manager
│   └── types.ts             # Strict TypeScript API schemas
├── .env.example             # Configuration settings template
├── CONTRIBUTING.md          # Open-source contribution guide
├── LICENSE                  # Open source MIT License
├── package.json             # Build dependencies and commands
└── tsconfig.json            # TypeScript compilation rules

---

⚙️ Installation & Setup

1. Build from Source

Ensure you have Node.js (v18.0.0 or higher) installed on your system.

# Clone the repository
git clone https://github.com/Investec-Developer-Community/investec-mcp-server.git
cd investec-mcp-server

# Install package dependencies
npm install

# Compile TypeScript to JavaScript
npm run build

2. Verify Connectivity (Sandbox Mode)

Run the sandbox integration test suite to verify that the server connects to the Investec developer sandbox API, fetches mock accounts, and reads balance sheets:

npm run test-sandbox

---

🔧 Environment Configuration

By default, the server runs in sandbox mode. To connect to your real live banking data, create a .env file in the root of the project (or copy .env.example to .env):

# 'production' to access live data, or 'sandbox' for mock accounts
INVESTEC_ENVIRONMENT=production

# Your Investec Developer credentials (obtained from Investec Online)
INVESTEC_CLIENT_ID=your_client_id
INVESTEC_CLIENT_SECRET=your_client_secret
INVESTEC_API_KEY=your_api_key

# Optional: Required for Advisor or Intermediary API scopes
INVESTEC_INTERMEDIARY_ID=your_intermediary_id

[!CAUTION] Keep your credentials secure! Never commit your .env file to public version control. The included .gitignore is pre-configured to block .env uploads.

---

💬 Claude Desktop Integration

To link the MCP server to your local Claude Desktop application, edit your claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the server specification under mcpServers:

{
  "mcpServers": {
    "investec-banking": {
      "command": "node",
      "args": [
        "C:/path/to/investec-mcp-server/dist/index.js"
      ]
    }
  }
}

Note: Make sure to replace C:/path/to/investec-mcp-server with the absolute path to your local project directory.

---

🛠️ Standalone SDK Usage

You can also import and use the underlying InvestecClient class as a standalone SDK in your own custom Node.js projects, independent of the MCP protocol:

import { InvestecClient } from "./src/investec-client";

async function main() {
  // Uses .env variables or falls back to public Sandbox defaults
  const client = new InvestecClient({ environment: "sandbox" });
  
  // List Accounts
  const response = await client.pbListAccounts();
  const accounts = response.data.accounts;
  
  console.log(`Found ${accounts.length} accounts.`);
}
main();

For a complete code demonstration, see [examples/pb-demo.ts](file:///c:/Users/jonel/Downloads/MCP_SERVER/examples/pb-demo.ts).

---

🧰 Exposed Tools Reference

The server registers the following MCP tools:

💳 Private Banking (PB)

Tool Name	Parameters	Description
investec_pb_list_accounts	None	List linked accounts ( cheque, savings, profiles ).
investec_pb_get_account_balance	accountId	Get available, current, and currency balance detail.
investec_pb_get_account_transactions	accountId, fromDate?, toDate?, transactionType?, includePending?	Fetch filtered transaction ledger feed.
investec_pb_get_pending_transactions	accountId	List outstanding pending transactions (e.g. card swipes).
investec_pb_list_profiles	None	List online profiles associated with user identity.
investec_pb_list_profile_accounts	profileId	List accounts associated with specific profile.
investec_pb_list_beneficiaries	None	Fetch registered payment beneficiaries.
investec_pb_pay_multiple	accountId, paymentList	Make batch payments to list of beneficiaries.
investec_pb_transfer_multiple	accountId, paymentList	Transfer funds between own accounts.
investec_pb_get_documents	accountId, fromDate?, toDate?	Retrieve list of statements and tax certificates.
investec_pb_get_document	accountId, documentType, documentDate	Fetch download link for specific statement PDF.

💻 Programmable Cards

Tool Name	Parameters	Description
investec_card_list_cards	None	List credit and debit cards linked to account.
investec_card_create_virtual_card	accountNumber, embossName, embossName2?	Issue virtual cards dynamically.
investec_card_get_code	cardKey	Get draft/working card JS scripts.
investec_card_update_code	cardKey, code	Upload new code draft for programmable cards.
investec_card_publish_code	cardKey	Publish and activate code for card swipe authorization.
investec_card_execute_code	cardKey, authorizationModel	Simulate card swipe swipe to test custom script logic.
investec_card_get_execution_history	cardKey	Fetch execution history logs of script.
investec_card_get_env_vars	cardKey	Retrieve script environment secrets.
investec_card_update_env_vars	cardKey, variables	Update script key-value environment secrets.
investec_card_toggle_programmable	cardKey	Turn programmable features on or off.

🏢 Corporate & Institutional Banking (CIB)

Tool Name	Parameters	Description
investec_cib_list_accounts	None	List corporate accounts.
investec_cib_get_account_transactions	accountId, fromDate?, toDate?, page?	Get corporate transaction ledger with pagination.
investec_cib_list_companies	None	List company entities under profile.
investec_cib_get_orders_shipments_report	companyName	Query current shipment and order status data.

---

📄 License

This project is open-source and released under the MIT License. Feel free to fork, distribute, and integrate this project in commercial and private setups. For official API support, consult the Investec Developer Portal.