Omise MCP Server

Version License TypeScript Node.js Docker

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

🚀 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

# Copy environment configuration file cp config/development.env .env # Set environment variables export OMISE_PUBLIC_KEY=pkey_test_xxxxxxxxxxxxxxxx export OMISE_SECRET_KEY=skey_test_xxxxxxxxxxxxxxxx export OMISE_ENVIRONMENT=test

3. Start Development Server

# Start in development mode npm run dev # Or start in production mode npm run build npm start

4. Verify Installation

# Health check curl http://localhost:3000/health # Check available tools curl http://localhost:3000/tools

📖 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! 🚀

This server cannot be installed

security - not tested

license - not tested

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables comprehensive payment processing through Omise APIs including charges, customers, transfers, refunds, disputes, recurring payments, and webhooks. Provides 51 tools covering all Omise API functionality for secure payment integration.

Omise MCP Server

🚀 Key Features

💳 Payment Processing

👥 Customer Management

🔄 Transfers & Recipients

📅 Schedules & Recurring Payments

🔍 Monitoring & Analytics

🔗 Links & Chains

📋 Supported APIs

🛠️ Technology Stack

🚀 Quick Start

Prerequisites

1. Installation

2. Environment Setup

3. Start Development Server

4. Verify Installation

📖 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

Development Guidelines

📈 Roadmap

v1.1.0 (Planned)

v1.2.0 (Planned)

📊 Statistics

New MCP Servers

MCP directory API