🔵 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.

Related MCP server: bank-mcp

📂 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

💬 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.

🧰 Exposed Tools Reference

The server registers the following MCP tools:

💳 Private Banking (PB)

💻 Programmable Cards

🏢 Corporate & Institutional Banking (CIB)

📄 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.