Skip to main content
Glama

Omise MCP Server

by jun-omise

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

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

  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

Technical Documentation

Support

๐Ÿ“„ License

This project is licensed under the MIT License.

๐Ÿค 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! ๐Ÿš€

-
security - not tested
A
license - permissive license
-
quality - not tested

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.

  1. ๐Ÿš€ Key Features
    1. ๐Ÿ’ณ Payment Processing
    2. ๐Ÿ‘ฅ Customer Management
    3. ๐Ÿ”„ Transfers & Recipients
    4. ๐Ÿ“… Schedules & Recurring Payments
    5. ๐Ÿ” Monitoring & Analytics
    6. ๐Ÿ”— Links & Chains
  2. ๐Ÿ“‹ Supported APIs
    1. ๐Ÿ› ๏ธ Technology Stack
      1. ๐Ÿš€ Quick Start
        1. Prerequisites
        2. 1. Installation
        3. 2. Environment Setup
        4. 3. Start Development Server
        5. 4. Verify Installation
      2. ๐Ÿ“– Usage
        1. Basic Payment Processing
        2. Recurring Payment Setup
        3. Transfer Processing
      3. ๐Ÿ”ง Configuration
        1. Environment Variables
        2. Obtaining Omise API Keys
      4. ๐Ÿ—๏ธ Project Structure
        1. ๐Ÿงช Development
          1. Development Environment Setup
          2. Testing
          3. Linting
          4. Build
        2. ๐Ÿณ Docker Deployment
          1. Development Environment
          2. Production Environment
          3. Automated Deployment
        3. ๐Ÿ“Š Monitoring & Logs
          1. Prometheus Metrics
          2. Grafana Dashboard
          3. Log Management
        4. ๐Ÿ”’ Security
          1. Security Features
          2. SSL/TLS Configuration
          3. Security Scanning
        5. ๐Ÿšจ Troubleshooting
          1. Common Issues
          2. Log Analysis
        6. ๐Ÿ“š API Reference
          1. Payment Tools
          2. Customer Tools
          3. Token Tools
        7. ๐Ÿ”— External Links
          1. Omise Official Documentation
          2. Technical Documentation
          3. Support
        8. ๐Ÿ“„ License
          1. ๐Ÿค Contributing
            1. Development Guidelines
          2. ๐Ÿ“ˆ Roadmap
            1. v1.1.0 (Planned)
            2. v1.2.0 (Planned)
          3. ๐Ÿ“Š Statistics

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/jun-omise/Omise-MCP-Alpha'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server