Skip to main content
Glama
jun-omise

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

  • Payment Links: Shareable payment links

  • Chain Management: Multi-tenant support

  • Capability Check: API functionality verification

Related MCP server: Fin-MCP Payment Server

๐Ÿ“‹ 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)

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

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    A
    maintenance
    Enables comprehensive integration with Kommo CRM through 25 tools for managing leads, contacts, companies, tasks, events, and generating detailed analytics reports. Supports advanced workflow management, pipeline operations, and real-time performance tracking.
    22
    14
    MIT
  • F
    license
    Not graded
    quality
    Not graded
    maintenance
    Enables AI agents to interact with multiple payment providers (Stripe, Paystack) through a unified API. Supports payment initialization, verification, refunds, customer management, and invoicing without requiring knowledge of specific provider implementations.
    2
    -
  • F
    license
    A
    quality
    D
    maintenance
    Enables interaction with the Conekta payment API to manage orders, customers, subscriptions, and financial transactions. It provides a comprehensive suite of tools for core payment operations like processing refunds, creating checkouts, and monitoring account balances.
    32
    2
    -
  • A
    license
    Not graded
    quality
    B
    maintenance
    Provides access to over 80 tools for managing OMICall and OMICRM APIs, including call center operations, ticket management, and multi-channel communication across platforms like Zalo and Facebook. It enables automated calling, agent management, and AI-powered text-to-speech capabilities through natural language.
    16 npm
    4
    MIT