ECOUNT MCP Server

English | 한국어

A Model Context Protocol (MCP) server for ECOUNT ERP OpenAPI integration.

Overview

This MCP server enables AI assistants like Claude to interact with ECOUNT ERP through natural language. It wraps ECOUNT's OpenAPI with proper session management, rate limiting, and caching.

Features

• 22 Tools - Products, customers, inventory, sales, purchases, production, accounting, e-commerce, attendance, bulletin board
• Automatic Session Management - Zone caching, session auto-renewal on expiry, file-based persistence
• Smart Throttling - Automatic rate limit management with intelligent waiting (no manual retry needed)
• Multi-Process Support - File-based rate limit state sharing across multiple instances
• Response Caching - 10-minute cache for query results
• Error Handling - Continuous error monitoring with user-friendly messages

Quick Start

Prerequisites

• ECOUNT ERP Account with Master ID privileges
• API Certificate Key (How to get one)
• Node.js 18+

Installation

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ecount": {
      "command": "npx",
      "args": ["-y", "mcp-server-ecount"],
      "env": {
        "ECOUNT_COM_CODE": "your_company_code",
        "ECOUNT_USER_ID": "your_user_id",
        "ECOUNT_API_CERT_KEY": "your_api_key"
      }
    }
  }
}

Claude Code

claude mcp add mcp-server-ecount -e ECOUNT_COM_CODE=회사코드 -e ECOUNT_USER_ID=사용자ID -e ECOUNT_API_CERT_KEY=인증키

Or add to your project's .mcp.json:

{
  "mcpServers": {
    "ecount": {
      "command": "npx",
      "args": ["-y", "mcp-server-ecount"],
      "env": {
        "ECOUNT_COM_CODE": "your_company_code",
        "ECOUNT_USER_ID": "your_user_id",
        "ECOUNT_API_CERT_KEY": "your_api_key"
      }
    }
  }
}

Tools

Connection & Status

Tool	Description
ecount_test_connection	Test API connection
ecount_get_session_info	Get current session status
ecount_server_status	Get server internal status (rate limits, cache, errors)

Products

Tool	Description	Rate Limit
ecount_get_product	Get single product details	1s
ecount_get_products	Get multiple products	10min
ecount_create_product	Create new products	10s

Customers

Tool	Description	Rate Limit
ecount_create_customer	Create new customers	10s

Inventory

Tool	Description	Rate Limit
ecount_get_inventory	Get inventory for single product	1s
ecount_get_inventory_list	Get inventory for multiple products	10min
ecount_get_inventory_by_warehouse	Get warehouse-level inventory (single)	1s
ecount_get_inventory_by_warehouse_list	Get warehouse-level inventory (multiple)	10min

Sales

Tool	Description	Rate Limit
ecount_create_quotation	Create quotation	10s
ecount_create_sale_order	Create sales order	10s
ecount_create_sale	Create sales slip	10s

Purchases

Tool	Description	Rate Limit
ecount_get_purchase_orders	Get purchase orders	10min
ecount_create_purchase	Create purchase slip	10s

Production

Tool	Description	Rate Limit
ecount_create_job_order	Create job order	10s
ecount_create_goods_issued	Create goods issued slip	10s
ecount_create_goods_receipt	Create goods receipt slip	10s

Accounting

Tool	Description	Rate Limit
ecount_create_invoice	Create sales/purchase invoice (auto journal)	10s

E-Commerce

Tool	Description	Rate Limit
ecount_create_openmarket_order	Import orders from online marketplaces	10s

Attendance

Tool	Description	Rate Limit
ecount_create_clock_in_out	Record attendance	10s

Bulletin Board

Tool	Description	Rate Limit
ecount_create_board_post	Create board post	10s

Configuration

Environment Variables

Variable	Required	Description
ECOUNT_COM_CODE	Yes	ECOUNT company code (6 digits)
ECOUNT_USER_ID	Yes	ECOUNT user ID (must be Master ID)
ECOUNT_API_CERT_KEY	Yes	API certificate key
ECOUNT_USE_TEST_SERVER	No	Use test server (true)
ECOUNT_SESSION_FILE	No	Session file path for persistence
ECOUNT_RATE_LIMIT_FILE	No	Rate limit state file for multi-process support
DEBUG	No	Enable debug logging (true)

API Certificate Key

1. Login to ECOUNT ERP with Master ID
2. Navigate to Self-Customizing > External Connection Settings > Open API Management
3. Apply for API usage and get certificate key
4. Start with test key for development, then get production key after verification

Note: Only Master ID can issue API certificate keys.

Rate Limits

ECOUNT OpenAPI has strict rate limits:

API Type	Production	Test Server
Zone/Login	10min	10s
Batch Query	10min	10s
Single Query	1s	1s
Save	10s	10s

Additional Limits

• Consecutive errors per hour: 30 (blocked if exceeded)
• Daily API calls: 5,000
• Max items per save: 300

Smart Throttling

This MCP server features intelligent rate limit management:

API Type	Auto-Wait	Max Wait
Single Query (1s)	✅ Yes	5s
Save (10s)	✅ Yes	15s
Batch Query (10min)	❌ No	Error
Zone/Login (10min)	❌ No	Error

• Auto-Wait: For short intervals (1s, 10s), the server automatically waits before retrying
• Multi-Process Safe: When ECOUNT_RATE_LIMIT_FILE is set, rate limit state is shared across all instances
• 100ms Safety Margin: All intervals include a safety margin to prevent edge-case failures

When rate limits are exceeded beyond auto-wait thresholds, friendly error messages are returned with remaining wait time.

Security

Never hardcode API credentials!

# Create .env file for development
ECOUNT_COM_CODE=your_code
ECOUNT_USER_ID=your_id
ECOUNT_API_CERT_KEY=your_key

# Add to .gitignore
echo ".env" >> .gitignore

Warning: Leaked ECOUNT credentials can compromise your entire ERP system.

Development

# Clone repository
git clone https://github.com/gilbreth-ai/mcp-server-ecount.git
cd mcp-server-ecount

# Install dependencies
npm install

# Build
npm run build

# Development mode
npm run dev

# Test with MCP Inspector
npm run inspect

Project Structure

mcp-server-ecount/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server setup
│   ├── client/
│   │   ├── ecount-client.ts  # API client
│   │   ├── session-manager.ts
│   │   ├── rate-limiter.ts
│   │   ├── cache.ts
│   │   └── error-counter.ts
│   ├── tools/
│   │   ├── register.ts       # Tool registration
│   │   └── schemas.ts        # Zod schemas
│   ├── types/
│   └── utils/
├── docs/                     # API documentation
├── package.json
└── README.md

Usage Examples

Check Inventory

User: "What's the inventory for product A001 across all warehouses?"

Claude uses ecount_get_inventory_by_warehouse tool.

Result:
- Main Warehouse: 100 units
- Distribution Center: 50 units
- Store: 25 units
Total: 175 units

Create Sales Slip

User: "Create a sale for customer C001, product A001, 10 units at 1000 won each"

Claude uses ecount_create_sale tool.

Result:
- Slip No: 20240115-1
- Success: 1 item

Low Stock Alert & Purchase Decision Support

User: "Show me items with less than 5 units in stock,
       with their recent purchase prices, and suggest order quantities"

Claude uses ecount_get_inventory_list, ecount_get_products tools.

Result:
- Product A: Stock 3, Last price 5,000 KRW → Suggest order: 20 units
- Product B: Stock 2, Last price 12,000 KRW → Suggest order: 15 units
- Product C: Stock 1, Last price 8,000 KRW → Suggest order: 25 units
Total estimated cost: 456,000 KRW

Natural Language Customer Registration

User: "Register new customer: ABC Corp, Business No. 123-45-67890,
       CEO: John Doe, Address: 123 Main St, Seoul"

Claude uses ecount_create_customer tool.

Result:
- Customer Code: C0042 (auto-generated)
- Registration complete

Post Analysis to ERP Bulletin Board

User: "Summarize our sales trend analysis and post it to the company bulletin board"

Claude uses ecount_create_board_post tool.

Result:
- Board: Announcements
- Title: [Analysis] H1 Sales Trend Summary
- Posted successfully

Troubleshooting

"Item not found" error when saving

You need to configure "Web Data Upload" in ECOUNT ERP:

1. Go to the input menu (e.g., Sales > Sales Input)
2. Click "Web Data Upload" button at the bottom
3. Add required fields with "Add Upload Items"

Session expires frequently

Increase auto-logout time in ERP settings:

• ERP Settings > Security Settings > Auto Logout Time

Rate limit exceeded

Wait for the cooldown period. Use ecount_server_status to check current rate limit status.

Disclaimer

This is a community project with no official affiliation to ECOUNT. Using ECOUNT OpenAPI requires a valid ECOUNT account and API certificate key. All API usage is subject to ECOUNT's terms of service.

License

MIT

Contributing

Bug reports, feature requests, and PRs are welcome!

• Issues
• Pull Requests