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

Related MCP server: MCP Server for Odoo

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

Products

Customers

Inventory

Sales

Purchases

Production

Accounting

E-Commerce

Attendance

Bulletin Board

Configuration

Environment Variables

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:

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:

• 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