Omise MCP Server

Omise MCP Server is a comprehensive server for integrating with Omise payment APIs using Model Context Protocol (MCP). Implemented in TypeScript with full support for Omise API v2017-11-02.

🚀 Key Features

💳 Payment Processing

Charge Management: Create, retrieve, update, capture, and reverse payments
Tokenization: Secure card information tokenization
Source Management: Support for various payment methods
Refunds: Partial and full refund processing

👥 Customer Management

Customer Information: Create, retrieve, update, and delete customers
Card Management: Manage customer card information
Metadata: Store custom information

🔄 Transfers & Recipients

Transfer Processing: Send money to recipients
Recipient Management: Create, verify, and manage recipients
Bank Accounts: Manage bank account information

📅 Schedules & Recurring Payments

Recurring Payments: Automatic payments based on schedules
Occurrence Management: Manage schedule execution
Flexible Configuration: Daily, weekly, and monthly schedules

🔍 Monitoring & Analytics

Event Management: Track system events
Dispute Management: Handle chargebacks
Webhooks: Real-time notifications

🔗 Links & Chains

Payment Links: Shareable payment links
Chain Management: Multi-tenant support
Capability Check: API functionality verification

📋 Supported APIs

Category	Features	Tool Count	Documentation
Payment	Charges, Tokens, Sources	8	Omise Charges API
Customer	Customer & Card Management	7	Omise Customers API
Transfer	Transfer & Recipient Management	6	Omise Transfers API
Refund	Refund Processing	3	Omise Refunds API
Dispute	Chargeback Processing	7	Omise Disputes API
Schedule	Recurring Payments	5	Omise Schedules API
Event	Event Management	2	Omise Events API
Webhook	Notification Management	5	Omise Webhooks API
Link	Payment Links	3	Omise Links API
Chain	Multi-tenant	4	Omise Chains API
Capability	Feature Verification	1	Omise Capabilities API

Total: 51 tools covering all Omise API functionality

🛠️ Technology Stack

Runtime: Node.js 20+
Language: TypeScript 5.2+
Framework: Model Context Protocol (MCP)
HTTP Client: Axios
Logging: Winston
Testing: Jest + MSW
Containerization: Docker + Docker Compose
Monitoring: Prometheus + Grafana
Caching: Redis
Log Aggregation: Loki

📊 Architecture Overview

The Omise MCP Server acts as an integration bridge between AI clients and the Omise Payment API, providing a secure and standardized way to process payments through conversational interfaces.

┌─────────────────┐    ┌─────────────────┐    ┌──────────────────┐
│   Claude/AI     │───▶│   MCP Server    │───▶│   Omise API      │
│   (Client)      │    │ (This Project)  │    │ (Payment Logic)  │
│                 │    │                 │    │                  │
│ • Natural Lang  │    │ • Protocol      │    │ • Authorization  │
│ • Tool Calls    │    │ • Validation    │    │ • Settlement     │
│ • Conversations │    │ • Formatting    │    │ • Fraud Detection│
│                 │    │ • Retry Logic   │    │ • PCI Compliance │
│                 │    │ • Rate Limiting │    │ • Bank Networks  │
└─────────────────┘    └─────────────────┘    └──────────────────┘

🔄 Data Flow

AI Client sends natural language request
MCP Protocol converts to structured tool calls
MCP Server validates and formats requests
Omise API processes payments and returns data
Response flows back through the chain to AI

🔐 Security Layers

MCP Protocol: Secure stdin/stdout communication
Input Validation: Parameter validation before API calls
Environment Isolation: Separate configs for test/production
API Authentication: Proper key management and rotation
Logging: Comprehensive audit trails (stderr only for MCP)

🚀 Benefits

AI-Native: Direct integration with Claude Desktop and other MCP clients
Type-Safe: Full TypeScript implementation with proper error handling
Reliable: Built-in retry logic, rate limiting, and error recovery
Secure: No business logic exposure - pure integration layer
Scalable: Docker deployment with monitoring and logging

🚀 Quick Start

Prerequisites

Node.js 20+
npm or yarn
Omise Account and API keys

1. Installation

# Clone the repository
git clone https://github.com/your-org/omise-mcp-server.git
cd omise-mcp-server

# Install dependencies
npm install

2. Environment Setup

2.1. Copy Configuration Template

# Copy environment configuration file for development
cp config/development.env .env

2.2. Get Your Omise API Keys

Sign up for an Omise Account
Log in to the Omise Dashboard
Navigate to Settings → API Keys
Copy your Test API keys:
- Public Key: pkey_test_xxxxxxxxxxxxxxxx (for tokenization)
- Secret Key: skey_test_xxxxxxxxxxxxxxxx (for API calls)

2.3. Configure Environment Variables

Option A: Edit .env file directly

# Edit the configuration file
nano .env

Update these critical settings in your .env file:

# ============================================================================
# Omise API Configuration (REQUIRED)
# ============================================================================
OMISE_PUBLIC_KEY=pkey_test_your_actual_public_key_here
OMISE_SECRET_KEY=skey_test_your_actual_secret_key_here
OMISE_ENVIRONMENT=test                    # Use 'test' for testing, 'production' for live
OMISE_API_VERSION=2019-05-29             # Omise API version
OMISE_BASE_URL=https://api.omise.co      # Main API endpoint
OMISE_VAULT_URL=https://vault.omise.co   # Secure tokenization endpoint
OMISE_TIMEOUT=30000                      # Request timeout in milliseconds

# ============================================================================
# Server Configuration
# ============================================================================
SERVER_NAME=omise-mcp-server-dev
SERVER_VERSION=1.0.0
NODE_ENV=development
LOG_LEVEL=info

# ============================================================================
# Rate Limiting
# ============================================================================
RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=100
RATE_LIMIT_WINDOW_MS=60000

Option B: Export as shell variables

# Set Omise API credentials
export OMISE_PUBLIC_KEY=pkey_test_your_actual_public_key_here
export OMISE_SECRET_KEY=skey_test_your_actual_secret_key_here
export OMISE_ENVIRONMENT=test
export OMISE_API_VERSION=2019-05-29
export OMISE_BASE_URL=https://api.omise.co
export OMISE_VAULT_URL=https://vault.omise.co

2.4. Environment-Specific Configuration

For Development:

cp config/development.env .env
# Use test API keys, enable verbose logging

For Staging:

cp config/staging.env .env
# Use test API keys, production-like settings

For Production:

cp config/production.env .env
# Use live API keys, optimized for performance
# OMISE_ENVIRONMENT=production
# OMISE_PUBLIC_KEY=pkey_live_xxxxxxxxxxxxxxxx
# OMISE_SECRET_KEY=skey_live_xxxxxxxxxxxxxxxx

2.5. Verify Configuration

# Test your API key configuration
npm run dev

# Or verify with a simple check
echo $OMISE_PUBLIC_KEY | grep -q "pkey_" && echo "✅ Public key configured" || echo "❌ Public key missing"
echo $OMISE_SECRET_KEY | grep -q "skey_" && echo "✅ Secret key configured" || echo "❌ Secret key missing"

3. Start Development Server

# Start in development mode
npm run dev

# Or start in production mode
npm run build
npm start

4. Verify Installation

# Test that the server starts without errors
npm run dev

# You should see:
# ✅ "Omise MCP Server started successfully"
# ✅ Server info with your configuration
# ✅ No authentication errors

5. Configure MCP Client

5.1. Claude Desktop Configuration

Create or edit Claude Desktop configuration:

macOS:

# Edit Claude Desktop config
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

# Edit Claude Desktop config  
notepad %APPDATA%\Claude\claude_desktop_config.json

Add your MCP server configuration:

{
  "mcpServers": {
    "omise-mcp-server": {
      "command": "/Users/your-username/.asdf/shims/npx",
      "args": ["tsx", "/path/to/your/project/src/index.ts"],
      "cwd": "/path/to/your/project",
      "env": {
        "NODE_ENV": "development",
        "OMISE_ENVIRONMENT": "test", 
        "OMISE_API_VERSION": "2019-05-29",
        "OMISE_PUBLIC_KEY": "pkey_test_your_actual_key_here",
        "OMISE_SECRET_KEY": "skey_test_your_actual_key_here",
        "OMISE_BASE_URL": "https://api.omise.co",
        "OMISE_VAULT_URL": "https://vault.omise.co",
        "OMISE_TIMEOUT": "30000"
      }
    }
  }
}

5.2. Other MCP Clients

For Cursor IDE:

{
  "servers": {
    "omise-mcp-server": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/path/to/omise-mcp-alpha",
      "env": {
        "OMISE_ENVIRONMENT": "test",
        "OMISE_PUBLIC_KEY": "your_public_key",
        "OMISE_SECRET_KEY": "your_secret_key"
      }
    }
  }
}

5.3. Test MCP Integration

Restart your MCP client (Claude Desktop, etc.) and verify:

✅ Server Connection: MCP client connects without errors
✅ Tools Available: Can see Omise payment tools
✅ Basic Test: Try creating a token or customer

Example test in Claude Desktop:

Create a test token with this card:
- Number: 4242424242424242
- Name: Test User  
- Expiry: 12/2025
- CVV: 123

📖 Usage

Basic Payment Processing

// Create a charge
const charge = await mcpClient.callTool('create_charge', {
  amount: 10000,        // 100.00 THB (smallest currency unit)
  currency: 'THB',
  description: 'Test payment',
  capture: true
});

// Create a customer
const customer = await mcpClient.callTool('create_customer', {
  email: 'customer@example.com',
  description: 'Test customer'
});

// Create a card token
const token = await mcpClient.callTool('create_token', {
  card: {
    name: 'John Doe',
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2025,
    security_code: '123'
  }
});

Recurring Payment Setup

// Create a schedule
const schedule = await mcpClient.callTool('create_schedule', {
  every: 1,
  period: 'month',
  start_date: '2024-01-01',
  charge: {
    customer: 'cust_123',
    amount: 5000,
    currency: 'THB',
    description: 'Monthly subscription'
  }
});

Transfer Processing

// Create a recipient
const recipient = await mcpClient.callTool('create_recipient', {
  name: 'John Doe',
  email: 'john@example.com',
  type: 'individual',
  bank_account: {
    brand: 'bbl',
    number: '1234567890',
    name: 'John Doe'
  }
});

// Execute transfer
const transfer = await mcpClient.callTool('create_transfer', {
  amount: 10000,
  recipient: recipient.id
});

🔧 Configuration

Environment Variables

Variable	Description	Required	Default
`OMISE_PUBLIC_KEY`	Omise public key	✓	-
`OMISE_SECRET_KEY`	Omise secret key	✓	-
`OMISE_ENVIRONMENT`	Environment (test/production)	✓	-
`PORT`	Server port	-	3000
`HOST`	Server host	-	localhost
`LOG_LEVEL`	Log level	-	info
`LOG_FORMAT`	Log format	-	simple
`RATE_LIMIT_ENABLED`	Enable rate limiting	-	true
`RATE_LIMIT_MAX_REQUESTS`	Maximum requests	-	100
`RATE_LIMIT_WINDOW_MS`	Time window (ms)	-	60000

Obtaining Omise API Keys

Access Omise Dashboard
Create an account or log in
Get keys from the API Keys section
Test Environment: Use keys starting with pkey_test_ and skey_test_
Production Environment: Use keys starting with pkey_live_ and skey_live_

Important: Always use live keys in production and test keys in test environment.

🏗️ Project Structure

omise-mcp-server/
├── src/                          # Source code
│   ├── index.ts                  # Main server file
│   ├── types/                    # Type definitions
│   │   ├── omise.ts             # Omise API type definitions
│   │   ├── mcp.ts               # MCP type definitions
│   │   └── index.ts             # Type definition exports
│   ├── tools/                    # Tool implementations
│   │   ├── payment-tools.ts     # Payment-related tools
│   │   ├── customer-tools.ts    # Customer-related tools
│   │   ├── token-tools.ts       # Token-related tools
│   │   ├── source-tools.ts      # Source-related tools
│   │   ├── transfer-tools.ts    # Transfer-related tools
│   │   ├── recipient-tools.ts  # Recipient-related tools
│   │   ├── refund-tools.ts      # Refund-related tools
│   │   ├── dispute-tools.ts     # Dispute-related tools
│   │   ├── schedule-tools.ts    # Schedule-related tools
│   │   ├── event-tools.ts       # Event-related tools
│   │   ├── webhook-tools.ts     # Webhook-related tools
│   │   ├── link-tools.ts        # Link-related tools
│   │   ├── chain-tools.ts       # Chain-related tools
│   │   ├── capability-tools.ts  # Capability verification tools
│   │   └── index.ts             # Tool exports
│   └── utils/                    # Utilities
│       ├── config.ts            # Configuration management
│       ├── logger.ts            # Logging functionality
│       ├── omise-client.ts      # Omise API client
│       ├── health-check.ts      # Health check
│       └── index.ts             # Utility exports
├── tests/                        # Tests
│   ├── unit/                     # Unit tests
│   ├── integration/              # Integration tests
│   ├── auth/                     # Authentication tests
│   ├── error/                    # Error handling tests
│   ├── rate-limit/               # Rate limiting tests
│   ├── mocks/                    # Mocks
│   └── factories/                # Test factories
├── config/                       # Configuration files
│   ├── development.env          # Development environment
│   ├── staging.env              # Staging environment
│   └── production.env            # Production environment
├── monitoring/                   # Monitoring configuration
│   ├── prometheus.yml            # Prometheus configuration
│   ├── loki-config.yml          # Loki configuration
│   └── grafana/                  # Grafana configuration
├── nginx/                        # Nginx configuration
├── docker-compose.yml            # Docker Compose configuration
├── Dockerfile                    # Docker configuration
├── package.json                  # Dependencies
├── tsconfig.json                 # TypeScript configuration
└── README.md                     # This file

🧪 Development

Development Environment Setup

# Install development dependencies
npm install

# Start development server
npm run dev

# Watch mode
npm run watch

Testing

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

# Specific test categories
npm run test:unit
npm run test:integration
npm run test:auth
npm run test:error
npm run test:rate-limit

Linting

# Run linting
npm run lint

# Auto-fix
npm run lint:fix

Build

# Compile TypeScript
npm run build

# Production build
npm run build:production

🐳 Docker Deployment

Development Environment

# Start development environment
docker-compose --env-file config/development.env up -d

# Check logs
docker-compose logs -f omise-mcp-server

Production Environment

# Start production environment
docker-compose --env-file config/production.env up -d

# Health check
curl http://localhost:3000/health
curl http://localhost:3000/ready
curl http://localhost:3000/live

Automated Deployment

# Run deployment script
./deploy.sh latest production

📊 Monitoring & Logs

Prometheus Metrics

URL: http://localhost:9090
Metrics: CPU, memory, request count, response time
Alerts: High load, error rate monitoring

Grafana Dashboard

URL: http://localhost:3001
Login: admin / admin (default)
Dashboards: System monitoring, application monitoring

Log Management

# Application logs
docker-compose logs -f omise-mcp-server

# Nginx logs
docker-compose logs -f nginx

# All service logs
docker-compose logs -f

🔒 Security

Security Features

Non-root user: Run containers as non-root user
Security headers: Proper HTTP header configuration
Rate limiting: API call restrictions
Sensitive data masking: Hide sensitive information in logs
Environment isolation: Complete separation of test and production environments

SSL/TLS Configuration

# Place SSL certificates
mkdir -p nginx/ssl
cp your-cert.pem nginx/ssl/cert.pem
cp your-key.pem nginx/ssl/key.pem

Security Scanning

# Container security scan
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  aquasec/trivy image omise-mcp-server:latest

🚨 Troubleshooting

Common Issues

1. Service Won't Start

# Check logs
docker-compose logs omise-mcp-server

# Check environment variables
docker-compose config

2. Health Check Fails

# Check health check endpoint directly
curl -v http://localhost:3000/health

# Check service connectivity
docker-compose exec omise-mcp-server ping redis

3. Memory Issues

# Check memory usage
docker stats

# Remove unnecessary containers
docker system prune -a

Log Analysis

# Check error logs
docker-compose logs omise-mcp-server | grep ERROR

# Analyze access logs
docker-compose logs nginx | grep "GET /"

📚 API Reference

Payment Tools

create_charge

Create a new charge.

Parameters:

amount (required): Amount in smallest currency unit
currency (required): Currency code (THB, USD, JPY, etc.)
description (optional): Charge description
customer (optional): Customer ID
card (optional): Card ID
source (optional): Source ID
capture (optional): Capture immediately (default: true)
return_uri (optional): Redirect URI
metadata (optional): Metadata

retrieve_charge

Retrieve charge information.

Parameters:

charge_id (required): Charge ID to retrieve

list_charges

List charges.

Parameters:

limit (optional): Number of items to retrieve (default: 20)
offset (optional): Offset (default: 0)
order (optional): Sort order (chronological/reverse_chronological)
status (optional): Status filter
customer (optional): Customer ID filter

Customer Tools

create_customer

Create a new customer.

Parameters:

email (optional): Customer email address
description (optional): Customer description
card (optional): Card ID
metadata (optional): Metadata

retrieve_customer

Retrieve customer information.

Parameters:

customer_id (required): Customer ID to retrieve

Token Tools

create_token

Create a secure card token for payment processing.

Parameters:

card (required): Card information
- name (required): Cardholder name
- number (required): Card number
- expiration_month (required): Expiration month (1-12)
- expiration_year (required): Expiration year (4 digits)
- city (optional): Billing address city
- postal_code (optional): Billing address postal code
- security_code (optional): Security code (CVV/CVC)

🔗 External Links

Omise Official Documentation

Technical Documentation

Support

GitHub Issues: Bug reports and feature requests
Omise Support: Omise official support
Community: Developer community

📄 License

This project is licensed under the MIT License.

🤝 Contributing

Contributions to the project are welcome! Please follow these steps:

Fork this repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Create a Pull Request

Development Guidelines

Write code in TypeScript
Maintain test coverage
Follow ESLint rules
Write clear commit messages

📈 Roadmap

v1.1.0 (Planned)

Additional payment method support
Advanced reporting features
Performance optimizations

v1.2.0 (Planned)

Enhanced multi-tenant support
Advanced monitoring features
Enhanced security features

📊 Statistics

Total Tools: 51
Supported APIs: 11 categories
Test Coverage: 95%+
TypeScript: 100%
Docker Support: ✅
Monitoring Support: ✅

Omise MCP Server - Achieve secure and efficient payment processing! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.idea		.idea
config		config
dist		dist
docs		docs
monitoring		monitoring
nginx		nginx
src		src
tests		tests
tools		tools
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README-DEPLOYMENT.md		README-DEPLOYMENT.md
README.md		README.md
deploy.sh		deploy.sh
docker-compose.yml		docker-compose.yml
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Omise MCP Server

🚀 Key Features

💳 Payment Processing

👥 Customer Management

🔄 Transfers & Recipients

📅 Schedules & Recurring Payments

🔍 Monitoring & Analytics

🔗 Links & Chains

📋 Supported APIs

🛠️ Technology Stack

📊 Architecture Overview

🔄 Data Flow

🔐 Security Layers

🚀 Benefits

🚀 Quick Start

Prerequisites

1. Installation

2. Environment Setup

2.1. Copy Configuration Template

2.2. Get Your Omise API Keys

2.3. Configure Environment Variables

2.4. Environment-Specific Configuration

2.5. Verify Configuration

3. Start Development Server

4. Verify Installation

5. Configure MCP Client

5.1. Claude Desktop Configuration

5.2. Other MCP Clients

5.3. Test MCP Integration

📖 Usage

Basic Payment Processing

Recurring Payment Setup

Transfer Processing

🔧 Configuration

Environment Variables

Obtaining Omise API Keys

🏗️ Project Structure

🧪 Development

Development Environment Setup

Testing

Linting

Build

🐳 Docker Deployment

Development Environment

Production Environment

Automated Deployment

📊 Monitoring & Logs

Prometheus Metrics

Grafana Dashboard

Log Management

🔒 Security

Security Features

SSL/TLS Configuration

Security Scanning

🚨 Troubleshooting

Common Issues

1. Service Won't Start

2. Health Check Fails

3. Memory Issues

Log Analysis

📚 API Reference

Payment Tools

create_charge

retrieve_charge

list_charges

Customer Tools

create_customer

retrieve_customer

Token Tools

create_token

🔗 External Links

Omise Official Documentation

Technical Documentation

Support

📄 License

🤝 Contributing

Packages