# Omise Mcp

> TypeScript library for integrating Omise payment APIs via an MCP server. Provides tools for payments, customers, transfers, refunds, and recurring billing.

- **Type:** MCP server
- **Install:** `agentstack add mcp-omise-omise-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [omise](https://agentstack.voostack.com/s/omise)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [omise](https://github.com/omise)
- **Source:** https://github.com/omise/omise-mcp
- **Website:** https://docs.omise.co/

## Install

```sh
agentstack add mcp-omise-omise-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)](https://modelcontextprotocol.io/). 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](https://docs.omise.co/charges-api)        |
| **Customer** | Customer & Card Management | 9 | [Omise Customers API](https://docs.omise.co/customers-api)     |
| **Transfer** | Transfers (5) & Recipients (6) | 11 | [Omise Transfers API](https://docs.omise.co/transfers-api)     |
| **Refund** | Refund Processing | 3 | [Omise Refunds API](https://docs.omise.co/refunds-api)         |
| **Dispute** | Chargeback & Document Management | 8 | [Omise Disputes API](https://docs.omise.co/disputes-api)       |
| **Schedule** | Recurring Payments | 5 | [Omise Schedules API](https://docs.omise.co/schedules-api)     |
| **Event** | Event Management | 2 | [Omise Events API](https://docs.omise.co/events-api)           |
| **Capability** | Feature Verification | 1 | [Omise Capabilities API](https://docs.omise.co/capability-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](https://dashboard.omise.co/) and API keys

### 1. Installation

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

# Install dependencies
npm install
```

### 2. Environment Setup

```bash
# 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:**
```bash
# 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:**
```bash
# 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

```bash
# 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

```bash
# Start in development mode
npm run dev

# Or start in production mode
npm run build
npm start
```

## 📖 Usage

### Basic Payment Processing

```typescript
// 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

```typescript
// 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

```typescript
// 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](https://dashboard.omise.co/)
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

```bash
# Install development dependencies
npm install

# Start development server
npm run dev
```

### Testing

```bash
# 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

```bash
# Run linting
npm run lint
```

### Build

```bash
# Compile TypeScript
npm run build

# Production build
npm run build:production
```

## 🐳 Docker Deployment

### Development Environment

```bash
# 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

```bash
# 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):**
```bash
export TOOLS=all
docker-compose up
```

**Read-only access (monitoring/analytics):**
```bash
export TOOLS=list_charges,retrieve_charge,list_customers,retrieve_customer
docker-compose up
```

**Payment processing only:**
```bash
export TOOLS=create_charge,retrieve_charge,capture_charge,create_customer,create_source
docker-compose up
```

**Podman with specific tools:**
```bash
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:**

```bash
# 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)
4. **Regular Audits**: Review and document tool access configurations periodically
5. **Environment Separation**: Use different TOOLS configurations for dev, staging, and production
6. **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:

```json
{
  "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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-omise-omise-mcp
- Seller: https://agentstack.voostack.com/s/omise
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.