Omise Model Context Protocol (MCP)

Let your AI agents interact with the Omise API by using our MCP server.

The Omise Model Context Protocol (MCP) server provides a set of tools for AI agents to interact with the Omise API for payment processing, customer management, and financial operations.

If you use AI-powered code editors such as Cursor or general-purpose tools such as Claude Desktop, you can use our MCP server.

Prerequisites

Before installing the Omise MCP server, ensure you have the following prerequisites installed:

Required Software

Node.js 20+: JavaScript runtime environment (includes the npm package manager)

Note: TypeScript and other dependencies will be automatically installed when you run npm install in the omise-mcp directory.

Installation Instructions

macOS

# Install Node.js using Homebrew
brew install node@20

# Verify installation
node --version
npm --version

Ubuntu/Debian

# Update package index
sudo apt update

# Install Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version

Omise API Keys

You need an Omise Account and API keys:

1. Access the Omise Dashboard
2. Create an account or log in
3. Navigate to Settings → Keys
4. Get your API keys:
   • 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 test keys during development and live keys only in production.

Local server

Run the local Omise MCP server by following the setup instructions for your preferred development environment.

Claude

To set up Omise MCP with Claude Desktop:

1. Download omise-mcp from GitHub
2. Navigate to the omise-mcp directory in a command prompt, then run npm install to install all dependencies.
3. Download and install Claude Desktop
4. Open Claude Desktop, navigate to Settings. Click Developer and then Edit Config.
   
5. Edit the claude_desktop_config.json file. The content should look as follows:

   {
     "mcpServers": {
       "omise-mcp-server": {
         "command": "/opt/homebrew/bin/npx",
         "args": [
           "tsx",
           "/path/to/your/omise-mcp/src/index.ts"
         ],
         "cwd": "/path/to/your/omise-mcp/",
         "env": {
           "NODE_ENV": "staging",
           "OMISE_ENVIRONMENT": "test",
           "OMISE_API_VERSION": "2019-05-29",
           "OMISE_PUBLIC_KEY": "<<YOUR_PUBLIC_KEY>>",
           "OMISE_SECRET_KEY": "<<YOUR_SECRET_KEY>>",
           "OMISE_BASE_URL": "https://api.staging-omise.co",
           "OMISE_VAULT_URL": "https://vault.staging-omise.co",
           "OMISE_TIMEOUT": "30000",
           "OMISE_RETRY_ATTEMPTS": "3",
           "OMISE_RETRY_DELAY": "1000",
           "SERVER_NAME": "omise-mcp-server-staging",
           "SERVER_VERSION": "1.0.0",
           "TOOLS": "all",
           "LOG_LEVEL": "info",
           "LOG_FORMAT": "json",
           "LOG_REQUESTS": "true",
           "LOG_RESPONSES": "false",
           "RATE_LIMIT_ENABLED": "true",
           "RATE_LIMIT_MAX_REQUESTS": "500",
           "RATE_LIMIT_WINDOW_MS": "60000"
         }
       }
     }
   }
   

   Note: Replace /path/to/your/omise-mcp/src/index.ts with the actual path to the index.ts file within your downloaded omise-mcp folder, and /path/to/your/omise-mcp/ with the exact path to your omise-mcp folder.
   
   API Keys: Replace <<YOUR_PUBLIC_KEY>> and <<YOUR_SECRET_KEY>> with your actual Omise API keys. You can obtain these from Omise Dashboard → Settings → Keys. For a live account, use live keys; for a test account, use test keys.

6. Save and close the file.
7. Restart Claude Desktop.
8. Navigate to Settings → Developer, and you should see that the Omise MCP server is running and connected to Claude.
   
9. From the Claude chat interface, click the Search and Tools icon. You should see the omise-mcp-server enabled.
   

Cursor

To set up Omise MCP with Cursor:

1. Download Cursor AI
2. Log in to the Cursor API
3. Navigate to Cursor → Settings → Cursor Settings → Tools & MCP
4. Click Add MCP Server
5. Enter the configuration as follows:

   {
     "mcpServers": {
       "omise-mcp-server": {
         "command": "/path/to/npx",
         "args": [
           "tsx",
           "/path/to/your/omise-mcp/src/index.ts"
         ],
         "cwd": "/path/to/your/omise-mcp",
         "env": {
           "NODE_ENV": "staging",
           "OMISE_ENVIRONMENT": "test",
           "OMISE_API_VERSION": "2019-05-29",
           "OMISE_PUBLIC_KEY": "<<YOUR_PUBLIC_KEY>>",
           "OMISE_SECRET_KEY": "<<YOUR_SECRET_KEY>>",
           "OMISE_BASE_URL": "https://api.staging-omise.co",
           "OMISE_VAULT_URL": "https://vault.staging-omise.co",
           "OMISE_TIMEOUT": "30000",
           "OMISE_RETRY_ATTEMPTS": "3",
           "OMISE_RETRY_DELAY": "1000",
           "SERVER_NAME": "omise-mcp-server-staging",
           "SERVER_VERSION": "1.0.0",
           "TOOLS": "all",
           "LOG_LEVEL": "info",
           "LOG_FORMAT": "json",
           "LOG_REQUESTS": "true",
           "LOG_RESPONSES": "false",
           "RATE_LIMIT_ENABLED": "true",
           "RATE_LIMIT_MAX_REQUESTS": "500",
           "RATE_LIMIT_WINDOW_MS": "60000"
         }
       }
     }
   }
   

   Note:

   • Replace /path/to/npx with the actual path to your npx executable (e.g., /Users/username/.asdf/shims/npx or /opt/homebrew/bin/npx)
   • Replace /path/to/your/omise-mcp/src/index.ts with the actual path to the index.ts file
   • Replace /path/to/your/omise-mcp with the actual path to your omise-mcp folder
   • Replace <<YOUR_PUBLIC_KEY>> and <<YOUR_SECRET_KEY>> with your actual Omise API keys from Omise Dashboard → Settings → Keys

6. Save the configuration
7. Restart Cursor
8. Navigate to Settings → Cursor Settings → Tools & MCP. The Omise MCP server should be enabled.
   

CLI

Start the MCP server locally with this command:

cd /path/to/your/omise-mcp
npx tsx src/index.ts

Ensure the OMISE_SECRET_KEY and OMISE_PUBLIC_KEY environment variables are set before running the server.

Configuration Parameters

Understanding the configuration parameters helps you customize the MCP server for your specific needs:

Core Configuration

URL Configuration

Network Configuration

Server Configuration

Logging Configuration

Rate Limiting Configuration

Access Control Configuration

Access Control Features:

• Tool Whitelisting: Only tools specified in the TOOLS environment variable are exposed to MCP clients
• Exact Validation: Tool names are validated against the complete list of 50+ available tools at startup
• Runtime Enforcement: Unauthorized tool calls are rejected with structured error messages
• Startup Validation: Server fails to start if invalid tool names are provided

Examples:

# Enable all tools
TOOLS=all

# Enable specific tools only
TOOLS=create_charge,retrieve_charge,list_charges

# Invalid tool name causes startup failure
TOOLS=invalid_tool # ❌ Fails with "Invalid tool names" error

Environment-Specific Configuration Samples

Development Environment:

{
  "NODE_ENV": "development",
  "OMISE_ENVIRONMENT": "test",
  "OMISE_PUBLIC_KEY": "pkey_test_...",
  "OMISE_SECRET_KEY": "skey_test_...",
  "TOOLS": "all",
  "LOG_LEVEL": "debug",
  "LOG_REQUESTS": "true",
  "LOG_RESPONSES": "true"
}

Staging Environment:

{
  "NODE_ENV": "staging",
  "OMISE_ENVIRONMENT": "test",
  "OMISE_BASE_URL": "https://api.staging-omise.co",
  "OMISE_VAULT_URL": "https://vault.staging-omise.co",
  "TOOLS": "all",
  "LOG_LEVEL": "info"
}

Production Environment:

{
  "NODE_ENV": "production",
  "OMISE_ENVIRONMENT": "production",
  "OMISE_PUBLIC_KEY": "pkey_live_...",
  "OMISE_SECRET_KEY": "skey_live_...",
  "TOOLS": "create_charge,retrieve_charge,list_charges,create_customer,retrieve_customer",
  "LOG_LEVEL": "warn",
  "LOG_RESPONSES": "false",
  "RATE_LIMIT_MAX_REQUESTS": "1000"
}

Tools

The server exposes the following MCP tools. Exercise caution when using the Omise MCP with other servers to avoid prompt injection attacks. Always review operations before they run, especially for sensitive actions like creating charges or processing payments. If you have feedback or want to see more tools, email us at mcp@omise.co.

Account

Retrieve and update account information.

Balance

Retrieve your Omise account balance information.

Charges

Create, retrieve, and manage charges for payment processing.

Customers

Create, retrieve, update, and delete customer records.

Cards

Manage customer cards for recurring payments.

Tokens

Create and retrieve tokens for secure card handling.

Sources

Create and retrieve payment sources for alternative payment methods.

Transfers

Create and manage fund transfers to recipients.

Recipients

Create and manage transfer recipients.

Refunds

Create and manage charge refunds.

Disputes

Manage and respond to payment disputes.

Documents

Upload and manage dispute evidence documents.

Schedules

Create and manage recurring payment schedules.

Occurrences

Retrieve scheduled payment occurrences.

Events

Retrieve webhook events for transaction monitoring.

Transactions

Retrieve transaction records that affect your account balance.

Receipts

Retrieve daily fee receipts.

Search

Search across multiple resource types.

Supported scopes: charge, customer, dispute, recipient, refund, transfer |

Forex

Retrieve foreign exchange rates for multi-currency transactions.

Capability

Retrieve account capabilities and available payment methods.

Payment Methods

The Omise MCP server supports a wide range of payment methods available through the Omise API, including:

• Credit/Debit Cards: Visa, Mastercard, JCB
• Internet Banking: Bangkok Bank, Kasikorn Bank, Siam Commercial Bank, Krung Thai Bank, and more
• Mobile Banking: PromptPay, TrueMoney Wallet
• E-wallets: Alipay, Alipay HK
• Installments: Various banks offering monthly terms

For the complete list of supported payment methods and their availability by country, use the retrieve_capability tool.

Security Best Practices

When using the Omise MCP server:

1. Use Test Keys During Development: Always use test mode API keys (starting with skey_test_ and pkey_test_) during development and testing.
2. Secure Your API Keys: Never commit API keys to version control or share them publicly. Store them as environment variables.
3. Implement Proper Error Handling: Always handle errors gracefully and never expose sensitive information in error messages.
4. Monitor for Suspicious Activity: Regularly review your API usage and set up alerts for unusual patterns.
5. Use Tool Whitelisting in Production: Instead of using TOOLS=all, specify only the tools your application needs. This follows the principle of least privilege and reduces the attack surface.

Error Handling

The Omise MCP server provides detailed error information when API calls fail. For example:

{
  "error": {
    "object": "error",
    "location": "https://docs.omise.co/api-errors",
    "code": "invalid_card",
    "message": "number is invalid"
  }
}

Common error codes:

• authentication_failure - Invalid API keys
• invalid_card - Card validation failed
• insufficient_fund - Not enough balance for operation
• failed_processing - Payment processing failed
• invalid_charge - Invalid charge parameters
• not_found - Resource not found
• service_not_available - Service temporarily unavailable

For a complete list of error codes, see the Omise API Errors documentation.

Testing

Test Mode

All Omise accounts have test mode enabled by default. Use test API keys to simulate transactions without processing real payments.

Test Cards

Use the following test card numbers in test mode:

Successful Charges: - 4242424242424242 - Visa - 5555555555554444 - Mastercard - 3530111333300000 - JCB

Failed Charges: - 4000000000000002 - Card declined - 4000000000000069 - Expired card - 4000000000000127 - Incorrect CVC

For a complete list of test cards and failure scenarios, see the Omise Testing Guide.

API Versioning

The Omise API uses versioning to ensure backward compatibility. The current recommended version is 2019-05-29.

To use a specific API version, set the OMISE_API_VERSION environment variable:

OMISE_API_VERSION=2019-05-29

For more information, see the Omise API Versioning documentation.

Usage Examples with Claude

Create a Charge using TOKEN

Create and Refund a Charge

List Available Tools

Support

If you encounter issues or have questions:

• Documentation: https://docs.omise.co
• API Status: https://status.omise.co
• Support Email: support@omise.co
• GitHub Issues: https://github.com/OmisePayments/omise-mcp/issues

See also

• Omise API Documentation
• Payment Methods Guide
• Security Best Practices
• Webhook Events
• Testing Guide
• API Errors