Mcp Server Ecount

ECOUNT MCP Server

[English](README.md) | [한국어](README_KO.md)

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

[](https://www.npmjs.com/package/mcp-server-ecount) [](https://opensource.org/licenses/MIT)

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](#api-certificate-key))
• 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

Source & license

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

• Author: storehausai
• Source: storehausai/mcp-server-ecount
• License: MIT
• Homepage: https://www.npmjs.com/package/mcp-server-ecount

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