investec-mcp

Investec MCP: Banking API for AI Agents

A Model Context Protocol (MCP) server implementation that integrates with the Investec Open Banking API, allowing AI agents to access banking information and perform transactions.

Overview

This project provides an MCP server that enables AI agents to interact with the Investec Open Banking API. It follows the best practices laid out by Anthropic for building MCP servers, allowing seamless integration with any MCP-compatible client like Claude.

Features

The server provides comprehensive banking tools based on the Investec Open Banking API:

Account Information

1. get_accounts: Retrieve all accounts for the authenticated user
2. get_account_balance: Get the balance for a specific account
3. get_account_transactions: Get transactions for a specific account with filtering options
4. get_pending_transactions: Get pending transactions for a specific account

Profile Management

5. get_profiles: Get all profiles the user has consented to
6. get_profile_accounts: Get accounts for a specific profile
7. get_profile_beneficiaries: Get beneficiaries for a specific profile and account
8. get_authorisation_setup_details: Get authorization setup details for payments requiring approval

Beneficiary Management

9. get_beneficiaries: Get all saved beneficiaries
10. get_beneficiary_categories: Get all beneficiary categories

Transfers and Payments

11. transfer_money: Transfer money between your own accounts (convenience method)
12. transfer_multiple: Transfer funds to one or multiple accounts in a batch
13. pay_beneficiary: Make a payment to a saved beneficiary (convenience method)
14. pay_multiple: Make payments to multiple beneficiaries in a batch

Document Management

15. get_documents: Get a list of documents for an account in a date range
16. get_document: Get a specific document by type and date

Prerequisites

• Python 3.12+
• Investec Developer account with API credentials
• Docker if running the MCP server as a container (recommended)

Installation

Using uv

1. Clone this repository:

   git clone https://github.com/yourusername/investec-mcp.git
   cd investec-mcp
   

2. Install dependencies:

   uv pip install -e .
   

3. Create a .env file based on .env.example:

   cp .env.example .env
   

4. Configure your environment variables in the .env file with your Investec API credentials

Using Docker (Recommended)

1. Build the Docker image:

   docker build -t investec/mcp --build-arg PORT=8050 .
   

2. Create a .env file based on .env.example and configure your environment variables

Configuration

The following environment variables can be configured in your .env file:

Running the Server

Using uv

SSE Transport

# Set TRANSPORT=sse in .env then:
uv run python src/main.py

The MCP server will run as an API endpoint that you can connect to.

Stdio Transport

With stdio, the MCP client itself can spin up the MCP server.

Using Docker

SSE Transport

docker run --env-file .env -p 8050:8050 investec/mcp

The MCP server will run as an API endpoint within the container that you can connect to.

Stdio Transport

With stdio, the MCP client itself can spin up the MCP server container.

Integration with MCP Clients

SSE Configuration

Once you have the server running with SSE transport, you can connect to it using this configuration:

{
  "mcpServers": {
    "investec": {
      "transport": "sse",
      "url": "http://localhost:8050/sse"
    }
  }
}

Note for Windsurf users: Use serverUrl instead of url in your configuration:

{
  "mcpServers": {
    "investec": {
      "transport": "sse",
      "serverUrl": "http://localhost:8050/sse"
    }
  }
}

Make sure to update the port if you are using a value other than the default 8050.

Python with Stdio Configuration

Add this server to your MCP configuration for Claude Desktop, Windsurf, or any other MCP client:

{
  "mcpServers": {
    "investec": {
      "command": "path/to/python",
      "args": ["path/to/investec-mcp/src/main.py"],
      "env": {
        "TRANSPORT": "stdio",
        "INVESTEC_CLIENT_ID": "your-client-id",
        "INVESTEC_CLIENT_SECRET": "your-client-secret",
        "INVESTEC_API_KEY": "your-api-key"
      }
    }
  }
}

Docker with Stdio Configuration

{
  "mcpServers": {
    "investec": {
      "command": "docker",
      "args": ["run", "--rm", "-i", 
               "-e", "TRANSPORT", 
               "-e", "INVESTEC_CLIENT_ID", 
               "-e", "INVESTEC_CLIENT_SECRET", 
               "-e", "INVESTEC_API_KEY", 
               "investec/mcp"],
      "env": {
        "TRANSPORT": "stdio",
        "INVESTEC_CLIENT_ID": "your-client-id",
        "INVESTEC_CLIENT_SECRET": "your-client-secret",
        "INVESTEC_API_KEY": "your-api-key"
      }
    }
  }
}

Security Considerations

This MCP server requires sensitive banking credentials. Always:

1. Keep your .env file secure and never commit it to version control
2. Use secure, private Docker registries if you build and distribute container images
3. Only run the server on secure, trusted networks
4. Consider implementing additional security measures like request rate limiting

Extending the Server

To add more functionality:

1. Add new methods to the InvestecClient class in src/utils.py to interact with the desired Investec API endpoints.
2. Create new tool functions within the relevant Python file inside the src/tools/ directory (e.g., src/tools/accounts.py for account-related tools). Use the @mcp.tool() decorator for these functions.
3. Import and register the new tool functions in src/main.py.