Content
# ECOUNT ERP MCP Server
This project wraps ECOUNT ERP's Open API with the [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server.
With this, you can query, create, and modify ECOUNT ERP data in natural language using LLMs like Claude.
## Overview
- **40 tool modules** — ECOUNT ERP core CRUD + logistics/finance/operations analysis + external integrations
- **Automatic session management** — login, automatic re-authentication on session expiration, and promise deduplication
- **Dual session isolation** — independent operation of Open API / Internal Web API failures
- **Circuit breaker** — automatic blocking of Internal API after 3 failures (30-second reset)
- **Type safety** — Zod schema validation for all inputs
- **Claude Desktop / Claude Code / Cursor compatibility** — based on StdioServerTransport
### Supported Categories
| Category | Tool Modules | Main Functions |
|---------|----------|----------|
| Connection/Auth | `connection` | login, session status check |
| Basic Information | `master-data` | items, customers, warehouses, departments, employees, accounts, projects |
| Sales | `sales` | sales slips, orders, sales unit prices, quotations |
| Purchases | `purchase` | purchase slips, orders |
| Inventory | `inventory` | inventory status, receipts, shipments, adjustments, barcodes |
| Production | `production` | production orders, production records, BOM |
| Accounting | `accounting` | accounting slips, general ledger, cash receipts |
| Board | `board` | board CRUD |
| Others | `other` | outsourcing, LOT tracking |
| Internal API | `internal-api` | ECOUNT internal web API (KeyPack protocol) |
| B/L Parser | `bl-parser` | bill of lading PDF parsing |
| Contacts | `contacts` | customer contact management |
| Business Rules | `business-rules` | ERP business rule queries |
| Contracts | `contracts` | contract management |
| Email | `email-templates` | email template generation |
| Shipment Tracking | `shipment-tracking` | shipment status tracking |
| Logistics KPI | `logistics-kpi` | logistics performance indicators |
| Customs/Costs | `customs-cost` | import customs and incidental costs calculation |
| Delayed Shipments | `stale-shipments` | detection of undelivered/ long-undelivered shipments |
| Inventory Verification | `inventory-verify` | inventory data integrity verification |
| Inventory Lifecycle | `inventory-lifecycle` | inventory aging/lifecycle analysis |
| Inventory Adjustment | `adjust-inventory` | inventory adjustment processing |
| Receivables | `receivables` | receivables analysis |
| Payables | `payables` | payables analysis |
| Weight Settlement | `weight-settlement` | weight-based settlement |
| Financial Statements | `financial-statements` | financial statement generation |
| Margin Analysis | `margin-analysis` | product/customer margin analysis |
| Dashboard | `dashboard` | management dashboard data aggregation |
| PDF Export | `pdf-export` | slip/report PDF generation |
| PDF Stamp | `pdf-stamp` | PDF document stamping |
| CSV Export | `csv-export` | data CSV conversion/export |
| Fax | `fax` | Popbill fax transmission |
| Daily Report | `daily-report` | daily work report generation |
| Health Check | `health-check` | API connection status check |
| Data Integrity | `data-integrity` | slip data integrity verification |
| Document Status | `document-status` | slip progress status tracking |
| Diagrams | `diagram` | Mermaid-based diagram rendering |
| Maps | `map` | logistics route map visualization |
| Presentations | `presentation` | slide presentation generation |
| 3D Visualization | `three-d` | 3D data visualization rendering |
## Prerequisites
- **Node.js** >= 18.0.0
- **ECOUNT ERP account** — Open API authentication key required (issued in [ECOUNT administrator settings](https://login.ecount.com/))
## Installation
### Method 1: Run with npx (recommended)
Can be used directly in Claude Desktop / Claude Code / Cursor settings without cloning.
Refer to the [Client Integration](#client-integration) section below.
### Method 2: Build from source
```bash
git clone https://github.com/hjsh200219/astrosECOUNT.git
cd astrosECOUNT
npm install
```
## Environment Variables
### Required (ECOUNT Open API)
| Variable | Description | Example |
|-----|------|-----|
| `ECOUNT_COM_CODE` | ECOUNT company code | `123456` |
| `ECOUNT_USER_ID` | ECOUNT user ID | `admin` |
| `ECOUNT_API_CERT_KEY` | API authentication key (issued by ECOUNT administrator) | `xxxxxxxx-xxxx-...` |
| `ECOUNT_ZONE` | server zone (`loginXX.ecount.com`'s `XX`) | `AA`, `AU1`, `AU2` etc. |
| `ECOUNT_LAN_TYPE` | language setting (default: `ko-KR`) | `ko-KR`, `en-US` |
| `ECOUNT_API_MODE` | API mode (default: `production`) | `production`, `sandbox` |
### Optional: Internal Web API
To use ECOUNT internal web API features, web login credentials are required.
| Variable | Description |
|-----|------|
| `ECOUNT_WEB_ID` | ECOUNT web login ID |
| `ECOUNT_WEB_PW` | ECOUNT web login password |
### Optional: Popbill Fax
To use fax transmission features, [Popbill](https://www.popbill.com/) integration settings are required.
| Variable | Description |
|-----|------|
| `POPBILL_LINK_ID` | Popbill link ID |
| `POPBILL_SECRET_KEY` | Popbill secret key |
| `POPBILL_IS_TEST` | test mode (default: `true`) |
### External MCP: korea-public-data-mcp
The following features are not included in this project and are provided by a separate **korea-public-data-mcp** server.
| Feature | Description |
|------|------|
| exchange rate/market rate | Korea Eximbank, customs office exchange rate queries |
| customs clearance | customs clearance information, cargo tracking, HS code, customs rate, etc. 51 APIs |
| livestock tracking | Ministry of Agriculture, Food and Rural Affairs MAFRA livestock tracking |
If you need exchange rate queries, customs clearance queries, or livestock tracking, call `korea-public-data-mcp`.
Refer to the [public-data MCP installation guide](docs/howto/10-public-data-setup-guide.md) for installation.
## Build and Run
```bash
# TypeScript build
npm run build
# Run server (stdio mode)
npm start
# Development mode (automatic restart on file changes)
npm run dev
```
## Client Integration
### Claude Desktop
Add the following to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"ecount-erp": {
"command": "npx",
"args": ["-y", "github:hjsh200219/astrosECOUNT"],
"env": {
"ECOUNT_COM_CODE": "company code",
"ECOUNT_USER_ID": "user ID",
"ECOUNT_API_CERT_KEY": "API authentication key",
"ECOUNT_ZONE": "AA",
"ECOUNT_LAN_TYPE": "ko-KR"
}
}
}
}
```
> **config file location**
> - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
> - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
### Claude Code
Add to `.claude/settings.json` or project root `.mcp.json`:
```json
{
"mcpServers": {
"ecount-erp": {
"command": "npx",
"args": ["-y", "github:hjsh200219/astrosECOUNT"],
"env": {
"ECOUNT_COM_CODE": "company code",
"ECOUNT_USER_ID": "user ID",
"ECOUNT_API_CERT_KEY": "API authentication key",
"ECOUNT_ZONE": "AA",
"ECOUNT_LAN_TYPE": "ko-KR"
}
}
}
}
```
### Cursor
Add a server in Cursor Settings > MCP or in project root `.cursor/mcp.json`:
```json
{
"mcpServers": {
"ecount-erp": {
"command": "npx",
"args": ["-y", "github:hjsh200219/astrosECOUNT"],
"env": {
"ECOUNT_COM_CODE": "company code",
"ECOUNT_USER_ID": "user ID",
"ECOUNT_API_CERT_KEY": "API authentication key",
"ECOUNT_ZONE": "AA",
"ECOUNT_LAN_TYPE": "ko-KR"
}
}
}
}
```
## Usage Examples
Ask Claude in natural language, and the MCP tool will be called automatically:
```
"Show me the sales slips for this month"
→ ecount_list_sale_slips called
"Tell me the inventory status of product code A001"
→ ecount_list_inventory_by_product called
"Create a quotation for customer B"
→ ecount_sales_save_quotation called
"Generate a margin analysis report for this month"
→ ecount_margin_analysis called
"Show me the management dashboard data"
→ ecount_dashboard called
"Check the ECOUNT session status"
→ ecount_connection_status called
```
## Development
```bash
# Run tests
npm test
# Test watch mode
npm run test:watch
# Type checking
npm run lint
# Debugging with MCP Inspector
npm run inspector
```
## Project Structure
```
astrosECOUNT/
├── src/
│ ├── index.ts # server entry point (stdio transport)
│ ├── server.ts # McpServer instance factory
│ ├── config.ts # environment variable validation (Zod)
│ ├── client/
│ │ ├── ecount-client.ts # Open API HTTP client
│ │ ├── session-manager.ts # Open API session management
│ │ ├── session-orchestrator.ts # dual session orchestration
│ │ ├── internal-api-client.ts # Internal Web API client
│ │ ├── internal-session.ts # Internal API session management
│ │ ├── keypack.ts # __$KeyPack encoder/decoder
│ │ ├── circuit-breaker.ts # Internal API circuit breaker
│ │ └── types.ts # ECOUNT API common types
│ ├── tools/
│ │ ├── index.ts # tool registration orchestrator
│ │ ├── tool-factory.ts # CRUD tool automatic registration factory
│ │ ├── connection.ts # authentication/connection
│ │ ├── master-data.ts # basic information
│ │ ├── sales.ts # sales
│ │ ├── purchase.ts # purchases
│ │ ├── inventory.ts # inventory
│ │ ├── production.ts # production
│ │ ├── accounting.ts # accounting
│ │ ├── board.ts # board
│ │ ├── other.ts # outsourcing, LOT
│ │ ├── internal-api.ts # internal web API
│ │ ├── ... # + 29 analysis/util/external integration tools
│ ├── types/
│ │ └── popbill.d.ts # Popbill type declarations
│ └── utils/
│ ├── response-formatter.ts # MCP response format helper
│ ├── error-handler.ts # error handling utility
│ ├── persistence.ts # data persistence utility
│ └── logger.ts # stderr logger
├── tests/ # Vitest unit/integration/E2E tests
├── docs/ # domain knowledge, API documentation, architecture
├── build/ # compilation output
└── package.json
```
## Tech Stack
- **TypeScript** v6 (ESM, strict) — type-safe development
- **@modelcontextprotocol/sdk** v1.28 — MCP protocol implementation
- **Zod** v4 — runtime input schema validation
- **pdf-lib** — PDF generation/editing
- **Vitest** v4 — unit/integration/E2E testing
- **tsx** — development TypeScript execution
## License
Private
