UK Open Banking MCP Server

A Java 21+ Spring Boot 3 Model Context Protocol (MCP) server that integrates UK Open Banking APIs with Claude Desktop, enabling natural language interactions with bank accounts, balances, transactions, and payments.

Table of Contents

• Features
• Architecture
• Prerequisites
• Installation
• Configuration
• Running the Server
• Claude Desktop Integration
• Testing
• Usage Examples
• Troubleshooting
• API Documentation
• Security
• Contributing

Features

Open Banking Capabilities

• Account Information (AISP)

  • Retrieve all bank accounts
  • Get account balances
  • Fetch transactions with date filtering

• Payment Initiation (PISP)

  • Initiate domestic payments
  • Support for GBP transfers

MCP Protocol Support

• Full JSON-RPC 2.0 implementation
• Tool discovery and invocation
• Stdio communication bridge for Claude Desktop
• Error handling and validation

Architecture

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────────┐
│  Claude Desktop │ ◄─────► │  MCP Stdio Bridge │ ◄─────► │  Spring Boot Server │
│                 │  stdio  │   (McpStdioBridge) │   HTTP  │   (Port 8080)      │
└─────────────────┘         └──────────────────┘         └─────────────────────┘
                                                                    │
                                                                    ▼
                                                          ┌─────────────────────┐
                                                          │  UK Open Banking    │
                                                          │  APIs               │
                                                          └─────────────────────┘

Prerequisites

• Java 21+ (recommend Java 25)
• Maven 3.8+
• Claude Desktop (latest version)
• UK Open Banking Credentials (from your bank's developer portal)

Check Prerequisites

# Check Java version
java -version  # Should be 21 or higher

# Check Maven
mvn -version

# Check Claude Desktop is installed
ls -la "/Applications/Claude.app"

Installation

1. Clone or Create the Project

mkdir -p ~/dev/learning/openbanking-mcp-server/
cd ~/dev/learning/openbanking-mcp-server/

This creates: target/OpenBankingMcpServerApplication-0.0.1-SNAPSHOT.jar

2. Create the Stdio Bridge

Create McpStdioBridge.java in the project root and compile it:

cd ~/dev/learning/mcpserver
# Copy the McpStdioBridge.java content from the artifact
javac McpStdioBridge.java

Configuration

Environment Variables

Create a .env file (optional):

# Open Banking Configuration
export OPENBANKING_CLIENT_ID="your_client_id"
export OPENBANKING_CLIENT_SECRET="your_client_secret"
export OPENBANKING_API_BASE_URL="https://api.sandbox.yourbank.co.uk"
export OPENBANKING_FINANCIAL_ID="your_financial_id"

# MCP Bridge Configuration
export MCP_SERVER_URL="http://localhost:8081/mcp"
export DEBUG="false"

Load environment:

source .env

Getting Open Banking Credentials

1. Register as a developer with a UK bank (e.g., NatWest, Lloyds, Barclays)
2. Create an application in their developer portal
3. Get credentials:
   • Client ID
   • Client Secret
   • Financial ID
   • API Base URL
4. Configure OAuth redirect URI: http://localhost:8080/login/oauth2/code/openbanking

Popular UK Banks Developer Portals

• NatWest/RBS: https://bankofapis.com/

Running the Server

Run Directly

cd ~/dev/learning/mcpserver
    mvn spring-boot:run

Verify Server is Running

# Check port
lsof -i :8081

# Test endpoint
curl -X POST http://localhost:8081/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

Expected response: JSON with 4 tools listed.

Claude Desktop Integration

1. Locate Claude Desktop Config

# macOS
~/Library/Application Support/Claude/claude_desktop_config.json

# Create directory if it doesn't exist
mkdir -p ~/Library/Application\ Support/Claude

2. Configure MCP Server

Edit claude_desktop_config.json:

Option A: Using Compiled .class File

{
  "mcpServers": {
    "uk-openbanking": {
      "command": "java",
      "args": [
        "-cp",
        "/Users/YOUR_USERNAME/dev/learning/openbanking-mcp-server/bridge",
        "McpStdioBridge"
      ],
      "env": {
        "MCP_SERVER_URL": "http://localhost:8081/mcp",
        "DEBUG": "false"
      }
    }
  }
}

Important: Replace your actual macOS file locations!

3. Restart Claude Desktop

4. Verify Connection

Look for the 🔌 icon in the bottom-right corner of Claude Desktop. Click it to see:

• uk-openbanking should show as "Connected"
• Green indicator means it's working

Testing

Manual Testing (Command Line)

Test 1: Initialize Connection

echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0"}},"id":1}' | java McpStdioBridge

Test 2: List Tools

echo '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}' | java McpStdioBridge

Test 3: Call Tool (will fail without valid token)

echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_accounts","arguments":{"access_token":"test_token"}},"id":1}' | java McpStdioBridge

Testing with Postman

Import these requests:

Collection: UK Open Banking MCP Server

1. Initialize

   • POST http://localhost:8080/mcp
   • Body: {"jsonrpc":"2.0","method":"initialize","params":{},"id":1}

2. List Tools

   • POST http://localhost:8080/mcp
   • Body: {"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}

3. Get Accounts

   • POST http://localhost:8080/mcp
   • Body:

   {
     "jsonrpc":"2.0",
     "method":"tools/call",
     "params":{
       "name":"get_accounts",
       "arguments":{"access_token":"YOUR_TOKEN"}
     },
     "id":1
   }
   

Testing in Claude Desktop

Once connected, try these natural language queries:

What banking tools do you have available?

Can you list my bank accounts? (requires valid OAuth token)

Show me the balance of account 12345678 (requires valid OAuth token)

Usage Examples

Example 1: Check Available Tools

User: "What Open Banking tools do you have?"

Claude Response:

I have access to 4 UK Open Banking tools:

1. get_accounts - Retrieve all bank accounts
2. get_balances - Get account balances for specific account
3. get_transactions - Fetch transactions with date filtering
4. initiate_payment - Initiate domestic GBP payments

Example 2: Get Account Balances

User: "Show me my account balances"

Claude: Will attempt to call the get_balances tool. Note: Requires valid OAuth access token.

Example 3: Analyze Spending

User: "What did I spend on groceries last month?"

Claude: Will call get_transactions with appropriate date range, then analyze the results.

Example 4: Make a Payment

User: "I need to pay £500 to account 12345678, sort code 12-34-56"

Claude: Will call initiate_payment with the provided details after confirmation.

API Documentation

Available Tools

1. get_accounts

Description: Retrieve all bank accounts for authenticated user

Parameters:

• access_token (string, required): OAuth2 access token

Returns: List of accounts with IDs, types, and identifiers

2. get_balances

Description: Get balances for a specific account

Parameters:

• account_id (string, required): Account identifier
• access_token (string, required): OAuth2 access token

Returns: Balance information including amount, currency, and type

3. get_transactions

Description: Retrieve transactions within date range

Parameters:

• account_id (string, required): Account identifier
• access_token (string, required): OAuth2 access token

Returns: List of transactions with amounts, dates, and descriptions

4. initiate_payment

Description: Initiate a domestic payment

Parameters:

• amount (string, required): Payment amount
• currency (string, required): Currency code (e.g., "GBP")
• creditor_account_number (string, required): Recipient account number
• creditor_sort_code (string, required): Recipient sort code
• reference (string, optional): Payment reference
• access_token (string, required): OAuth2 access token

Returns: Payment initiation response with status

MCP Protocol Methods

• initialize - Establish connection
• tools/list - Get available tools
• tools/call - Invoke a tool
• resources/list - List resources (empty)
• prompts/list - List prompts (empty)

Project Structure

mcpserver/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/openbanking/mcp/
│   │   │       ├── OpenBankingMcpServerApplication.java
│   │   │       ├── controller/
│   │   │       │   └── McpController.java
│   │   │       ├── service/
│   │   │       │   └── OpenBankingService.java
│   │   │       ├── model/
│   │   │       │   ├── McpRequest.java
│   │   │       │   ├── McpResponse.java
│   │   │       │   └── openbanking/
│   │   │       │       ├── Account.java
│   │   │       │       ├── Balance.java
│   │   │       │       └── Transaction.java
│   │   │       └── config/
│   │   │           └── SecurityConfig.java
│   │   └── resources/
│   │       └── application.yml
├── target/
│   └── OpenBankingMcpServerApplication-0.0.1-SNAPSHOT.jar
├── McpStdioBridge.java
├── McpStdioBridge.class
├── mcp-bridge.jar (optional)
├── pom.xml
└── README.md