Wise MCP Node Server

A TypeScript implementation of an MCP (Model Context Protocol) server that integrates with Wise's API, enabling AI assistants to perform financial operations through Wise.

🚀 Features

• 📡 Multiple Transports - STDIO and HTTP/HTTPS support
• 💰 Wise API Integration - Profile, balance, quote, and recipient management
• 🔐 OAuth2 Support - Secure authentication flow
• 🐳 Docker Ready - Multi-stage builds for production
• 📝 MCP Compliant - Full Model Context Protocol implementation

📋 Prerequisites

• Node.js >= 22.17.0
• npm or yarn
• Docker (optional, for containerized deployment)

🛠️ Installation

Multiple installation methods are available. See the Installation Guide for detailed instructions.

Quick Install

# Clone and install
git clone https://github.com/kstam/wise-mcp.git
cd wise-mcp-node
npm install
npm run build

# Via Docker
docker build -t wise-mcp-node .
docker run -it --rm -e WISE_API_TOKEN="your-token" wise-mcp-node

🚦 Quick Start

1. Get your Wise API token from Wise Platform
2. Set your environment variables:

   export WISE_API_TOKEN="your-token"
   export WISE_API_URL="https://api.sandbox.transferwise.tech"  # or production URL
   export MCP_TRANSPORT="stdio"  # or "http" for HTTP transport

3. Run the server:

   npm start

For development setup, see the Development section below.

🔧 Development

Available Scripts

# Development
npm run dev:watch        # Start with hot reload
npm run build            # Compile TypeScript
npm run typecheck        # Type checking without emit

# Testing
npm test                 # Run all tests
npm run test:watch       # Watch mode
npm run test:coverage    # Generate coverage report
npm run test:unit        # Unit tests only
npm run test:e2e         # E2E tests only

# Code Quality
npm run lint             # ESLint check
npm run lint:fix         # Auto-fix linting issues
npm run format           # Check formatting
npm run format:fix       # Auto-fix formatting

# Utilities
npm run clean            # Remove build artifacts

Environment Variables

Core Configuration

• MCP_TRANSPORT - Transport type: "stdio" or "http" (default: stdio)
• LOG_LEVEL - Logging verbosity: debug/info/warn/error (default: error)
• NODE_ENV - Environment: development/production/test

Wise API Configuration

• WISE_API_TOKEN - Your Wise API token (required for STDIO)
• WISE_API_URL - Wise API endpoint (default: https://api.sandbox.transferwise.tech)
• WISE_API_CLIENT_ID - OAuth2 client ID (for HTTP transport)
• WISE_API_CLIENT_SECRET - OAuth2 client secret (for HTTP transport)
• WISE_PROFILE_ID - Default profile ID (optional)

HTTP Transport Configuration

• SERVER_PROTOCOL - Protocol: http/https (default: http)
• SERVER_HOST - Server hostname (default: localhost)
• SERVER_PORT - Server port (default: 80 for http, 443 for https)

HTTPS TLS Configuration

• TLS_KEY_PATH - Path to TLS private key file
• TLS_CERT_PATH - Path to TLS certificate file
• TLS_CA_PATH - Path to CA certificate file (optional)
• TLS_PASSPHRASE - TLS key passphrase (optional)

Generate TLS certificates for development:

./scripts/generate-certs.sh

🧩 Tool Development

Available Tools

• Profile: listProfiles - List all Wise profiles
• Balance: getBalance - Get balance for a profile
• Quotes:
  • createQuote, createQuoteUnauthenticated - Create transfer quotes
  • getQuote - Retrieve quote details
  • updateQuote - Update existing quotes
• Recipients:
  • listRecipients, getRecipient - Manage recipients
  • createRecipient, deactivateRecipient - Create/remove recipients
  • accountRequirements - Get account requirements by country

Creating a New Tool

1. Create a new file in src/tools/{domain}/
2. Follow the same approach as in existing tools
3. Register in src/tools/index.ts
4. Add tests in tool directory

Best Practices

• ✅ Always validate inputs using Zod schemas
• ✅ Return consistent ToolResult format
• ✅ Handle errors gracefully with proper error codes
• ✅ Log important operations to stderr
• ✅ Write comprehensive tests (unit and integration)
• ✅ Use authentication context when required
• ❌ Never write to stdout (breaks MCP protocol)
• ❌ Don't use console.log (use structured logging)

🐳 Docker

Production Build

# Build production image
docker build -t wise-mcp-node .

# Run production container
docker run --rm -it wise-mcp-node

Coverage Requirements

• Minimum 80% coverage for:
  • Statements
  • Branches
  • Functions
  • Lines

🔍 Debugging

Using MCP Inspector

# Run with MCP Inspector
npm run inspect-mcp

# Or manually:
npm run build
npx @modelcontextprotocol/inspector node -- dist/index.js

Logging

Logs are written to stderr with structured JSON format:

const logger = createLogger('component-name');
logger.info('Operation completed', { userId: 123, duration: 45 });

🚀 Deployment

Environment Setup

1. Set production environment variables
2. Build the application: npm run build
3. Run with: NODE_ENV=production node dist/index.js

Docker Deployment

# Build and tag
docker build -t wise-mcp-node:latest .

# Run with environment variables
docker run --env-file .env wise-mcp-node:latest

📋 Releases

This project uses Changesets for version management. See RELEASING.md for details.

# Create a changeset
npm run changeset

# Version packages
npm run changeset:version

# Publish (after building and testing)
npm run release

🤝 Contributing

Development Workflow

1. Create feature branch
2. Write tests first (TDD)
3. Implement feature
4. Run validation: npm run lint && npm test && npm run build
5. Update documentation
6. Submit PR

Code Style

• Follow TypeScript strict mode
• Use ESLint rules
• Format with Prettier
• Write JSDoc comments for public APIs

📚 Resources

• MCP Specification
• TypeScript Documentation
• Jest Testing Guide
• Docker Best Practices

🐛 Troubleshooting

Common Issues

TypeScript compilation errors:

npm run typecheck  # Check for type errors
npm run build      # Full compilation

Test failures:

npm test -- --verbose  # Detailed test output

Docker build issues:

docker build --no-cache -t wise-mcp-node .  # Rebuild from scratch

Getting Help

1. Check existing issues
2. Review test files for usage examples
3. Enable debug logging: LOG_LEVEL=debug npm run dev

📄 License

MIT