Omise Mcp

Omise MCP Server

[](https://github.com/omise/omise-mcp) [](LICENSE) [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](https://www.docker.com/) [](https://github.com/omise/omise-mcp/releases)

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 v2019-05-29.

> ⚠️ Alpha Release: This is an alpha release for early adopters and testing. Some features may be experimental.

🚀 Key Features

💳 Payment Processing

• Charge Management: Create, retrieve, update, capture, and reverse payments
• 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
• Capability Check: API functionality verification

📋 Supported APIs

| Category | Features | Tool Count | Documentation | |---------|----------|------------|---------------------------------------------------------------| | Payment | Charges (7), Sources (2) | 9 | Omise Charges API | | Customer | Customer & Card Management | 9 | Omise Customers API | | Transfer | Transfers (5) & Recipients (6) | 11 | Omise Transfers API | | Refund | Refund Processing | 3 | Omise Refunds API | | Dispute | Chargeback & Document Management | 8 | Omise Disputes API | | Schedule | Recurring Payments | 5 | Omise Schedules API | | Event | Event Management | 2 | Omise Events API | | Capability | Feature Verification | 1 | Omise Capabilities API |

Total: 48 tools covering all active Omise Core API functionality

🛠️ Technology Stack

• Runtime: Node.js 20+
• Language: TypeScript 5.2+
• Framework: Model Context Protocol (MCP)
• HTTP Client: Axios
• Logging: Winston
• Testing: Jest
• Containerization: Docker + Docker Compose

🚀 Quick Start

Prerequisites

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

1. Installation

# Clone the repository
git clone git@github.com:omise/omise-mcp.git
cd omise-mcp

# Install dependencies
npm install

2. Environment Setup

# Copy environment configuration file
cp config/production.env.example .env
# Or use staging template: cp config/staging.env.example .env

# Set environment variables
export OMISE_SECRET_KEY=skey_test_xxxxxxxxxxxxxxxx
export OMISE_ENVIRONMENT=test
export OMISE_API_VERSION=2019-05-29
export OMISE_BASE_URL=https://api.omise.co

# Set tool access control (mandatory)
export TOOLS=all  # For development only
# Or for production, specify exact tools:
# export TOOLS=create_charge,retrieve_charge,list_charges,create_customer

2.4. Environment-Specific Configuration

For Development:

# Copy example file and customize
cp config/production.env.example .env
# Edit .env and set OMISE_ENVIRONMENT=test
# Use test API keys, enable verbose logging

For Production:

# Copy example file and customize
cp config/production.env.example .env
# Edit .env and set:
# OMISE_ENVIRONMENT=production
# OMISE_SECRET_KEY=skey_live_xxxxxxxxxxxxxxxx
# Use live API keys, optimized for performance

2.5. Verify Configuration

# Test your API key configuration
npm run dev

# Or verify with a simple check
echo $OMISE_SECRET_KEY | grep -q "skey_" && echo "✅ Secret key configured" || echo "❌ Secret key missing"
echo $TOOLS | grep -q "." && echo "✅ TOOLS configured: $TOOLS" || echo "❌ TOOLS not set (required)"

3. Start Development Server

# Start in development mode
npm run dev

# Or start in production mode
npm run build
npm start

📖 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'
});

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_SECRET_KEY | Omise secret key | ✓ | - | | OMISE_ENVIRONMENT | Environment (test/production) | ✓ | - | | TOOLS | Comma-separated list of allowed tools or 'all' | ✓ | - | | LOG_LEVEL | Log level | - | info | | LOG_FORMAT | Log format | - | simple |

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 skey_test_
5. Production Environment: Use keys starting with 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
│   │   ├── 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
│   │   ├── 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
│       └── index.ts             # Utility exports
├── tests/                        # Tests
│   ├── unit/                     # Unit tests
│   ├── integration/              # Integration tests
│   ├── auth/                     # Authentication tests
│   ├── error/                    # Error handling tests
│   └── factories/                # Test factories
├── config/                       # Configuration files
│   ├── production.env.example    # Production template
│   └── staging.env.example      # Staging template
├── 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

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

Linting

# Run linting
npm run lint

Build

# Compile TypeScript
npm run build

# Production build
npm run build:production

🐳 Docker Deployment

Development Environment

# Start development environment
# First create your .env file from the example:
# cp config/production.env.example .env
# Edit .env with your test API keys
docker-compose --env-file .env up -d

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

Production Environment

# Start production environment
# First create your .env file from the example:
# cp config/production.env.example .env
# Edit .env with your live API keys
docker-compose --env-file .env up -d

🔒 Security

Security Features

• Non-root user: Run containers as non-root user
• Sensitive data masking: Hide sensitive information in logs
• Environment isolation: Complete separation of test and production environments
• Tool Access Control: Granular control over which API tools clients can access

Tool Access Control

The MCP server requires explicit tool access configuration for enhanced security. Each client must specify which Omise API tools they are authorized to use.

Configuration

Set the TOOLS environment variable (mandatory). The server will not start without this configuration.

Options:

• TOOLS=all - Full access to all 48 tools (development only, not recommended for production)
• TOOLS=tool1,tool2,... - Comma-separated list of specific tools (recommended for production)

Common Patterns:

• Read-only access: TOOLS=list_charges,retrieve_charge,list_customers,retrieve_customer
• Payment processing: TOOLS=create_charge,retrieve_charge,capture_charge,create_customer,create_source
• Finance operations: TOOLS=list_charges,retrieve_charge,create_refund,create_transfer

Examples

Full access (development/testing):

export TOOLS=all
docker-compose up

Read-only access (monitoring/analytics):

export TOOLS=list_charges,retrieve_charge,list_customers,retrieve_customer
docker-compose up

Payment processing only:

export TOOLS=create_charge,retrieve_charge,capture_charge,create_customer,create_source
docker-compose up

Podman with specific tools:

podman run --rm -i \
  -e OMISE_SECRET_KEY=skey_test_xxx \
  -e OMISE_ENVIRONMENT=test \
  -e TOOLS=create_charge,list_charges,create_customer \
  omise-mcp-server:latest

Available Tools by Category

| Category | Tools | Description | |----------|-------|-------------| | Charges | create_charge, retrieve_charge, list_charges, update_charge, capture_charge, reverse_charge, expire_charge | Payment charge operations | | Customers | create_customer, retrieve_customer, list_customers, update_customer, destroy_customer | Customer management | | Cards | list_customer_cards, retrieve_customer_card, update_customer_card, destroy_customer_card | Card management | | Sources | create_source, retrieve_source | Payment sources | | Transfers | create_transfer, retrieve_transfer, list_transfers, update_transfer, destroy_transfer | Transfer operations | | Recipients | create_recipient, retrieve_recipient, list_recipients, update_recipient, destroy_recipient, verify_recipient | Recipient management | | Refunds | create_refund, retrieve_refund, list_refunds | Refund processing | | Disputes | list_disputes, retrieve_dispute, accept_dispute, update_dispute, list_dispute_documents, retrieve_dispute_document, upload_dispute_document, destroy_dispute_document | Dispute handling | | Schedules | create_schedule, retrieve_schedule, list_schedules, destroy_schedule, list_schedule_occurrences | Recurring payments | | Events | list_events, retrieve_event | Event tracking | | Capabilities | retrieve_capability | Feature verification |

Error Handling

The server will fail to start if:

• TOOLS environment variable is not set
• TOOLS is empty or contains only whitespace
• TOOLS contains invalid tool names (e.g., TOOLS=hello,invalid_tool)

Clients will receive an authorization error if:

• They attempt to call a tool not in their allowed list

Example Errors:

# Missing TOOLS environment variable
Error: Missing required environment variable: TOOLS
Set TOOLS=all for full access, or specify comma-separated tool names.
Example: TOOLS=create_charge,list_charges,create_customer

# Invalid tool names
Error: Invalid tool names: hello, invalid_tool
Valid tools are: create_charge, retrieve_charge, list_charges, ... (48 total)
Use TOOLS=all for full access.

Runtime Behavior:

When TOOLS is properly configured:

• Only authorized tools appear in list_tools responses
• Unauthorized tools are not accessible to clients
• Access control is enforced at the MCP protocol level

Security Best Practices

1. Principle of Least Privilege: Only grant access to tools absolutely necessary for the role
2. Production Restrictions: Never use TOOLS=all in production - always specify exact tools
3. Role-Based Deployment: Run separate MCP server instances for different user roles:

• Read-Only (Analytics/Support): list_charges,retrieve_charge,list_customers,retrieve_customer
• Payment Processing (Merchants): create_charge,retrieve_charge,capture_charge,create_customer,create_source
• Finance Operations: list_charges,create_refund,create_transfer,create_recipient
• Admin (Development/Emergency): all (use with caution)

1. Regular Audits: Review and document tool access configurations periodically
2. Environment Separation: Use different TOOLS configurations for dev, staging, and production
3. Configuration Management: Store TOOLS settings in environment-specific config files

Multiple Client Configurations

Use Cursor's mcp.json to configure multiple clients with different access levels:

{
  "mcpServers": {
    "omise-admin": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "OMISE_SECRET_KEY=skey_xxx",
        "-e", "OMISE_ENVIRONMENT=production",
        "-e", "TOOLS=all",
        "omise-mcp-server:latest"
      ]
    },
    "omise-readonly": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "OMISE_SECRET_KEY=skey_xxx",
        "-e", "OMISE_ENVIRONMENT=production",
        "-e", "TOOLS=list_charges,retrieve_charge,list_customers,retrieve_customer",
        "omise-mcp-server:latest"
      ]
    },
    "omise-payment"

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [omise](https://github.com/omise)
- **Source:** [omise/omise-mcp](https://github.com/omise/omise-mcp)
- **License:** Apache-2.0
- **Homepage:** https://docs.omise.co/

Install and usage instructions live in the source repository linked above.