nitishomise/omise-mcp-playground

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

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

1. AI Client sends natural language request
2. MCP Protocol converts to structured tool calls
3. MCP Server validates and formats requests
4. Omise API processes payments and returns data
5. 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

1. Sign up for an Omise Account
2. Log in to the Omise Dashboard
3. Navigate to Settings → API Keys
4. 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:

1. ✅ Server Connection: MCP client connects without errors
2. ✅ Tools Available: Can see Omise payment tools
3. ✅ 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

Obtaining Omise API Keys

1. Access Omise Dashboard
2. Create an account or log in
3. Get keys from the API Keys section
4. Test Environment: Use keys starting with pkey_test_ and skey_test_
5. 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

• Omise API Documentation
• Omise Charges API
• Omise Customers API
• Omise Transfers API
• Omise Refunds API
• Omise Disputes API
• Omise Schedules API
• Omise Events API
• Omise Webhooks API
• Omise Links API
• Omise Chains API
• Omise Capabilities API

Technical Documentation

• Model Context Protocol (MCP)
• Docker Documentation
• Docker Compose Documentation
• Prometheus Documentation
• Grafana Documentation
• Redis Documentation
• Loki Documentation

Support

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

📄 License

This project is licensed under the .

🤝 Contributing

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

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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! 🚀