epicor-unified-mcp

Airstage-AI/epicor-unified-mcp

3.2

If you are the rightful owner of epicor-unified-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Epicor Unified MCP Server provides a unified interface to access 899 Epicor services using standardized CRUD operations.

Tools
4
Resources
0
Prompts
0

Epicor Unified MCP Server

A unified Model Context Protocol (MCP) server that provides access to 899 Epicor services through a single, dynamically configurable interface. This server enables AI assistants to interact with Epicor ERP systems using standardized CRUD operations.

Generated with: This MCP server was generated using the openapi-mcp-generator tool, which converts OpenAPI specifications into fully functional MCP servers with TypeScript support, Zod validation, and multiple transport options.

🚀 Features

  • 899 Epicor Services: Access to all available Epicor REST API endpoints
  • Dynamic Configuration: Enable/disable services without code changes
  • Generic CRUD Operations: Unified Get, Post, Patch, Delete tools for any service
  • OData Support: Full OData query support (filtering, sorting, pagination)
  • Multiple Transports: Supports both stdio and HTTP transports
  • Production Ready: Optimized for production deployment

📋 Prerequisites

  • Node.js >= 20.0.0
  • Access to Epicor ERP system
  • Epicor API credentials

🛠️ Installation

Option 1: Clone and Install

git clone <repository-url>
cd epicor-unified-mcp
npm install
npm run build

Option 2: Global Installation

npm install -g epicor-unified-mcp

⚙️ Configuration

Environment Variables

Create a .env file in the project root:

# Epicor API Configuration
EPICOR_API_KEY=your_api_key_here
EPICOR_USERNAME=your_username
EPICOR_PASSWORD=your_password

# Optional: Custom API Base URL
EPICOR_API_URL=https://your-epicor-instance.com/api/v2/odata

Service Configuration

The server uses services-config.json to manage available services. By default, it includes 20 core services, but can be configured to include all 899 available services.

Default Services Included:
  • CustomerSvc, PartSvc, VendorSvc, SalesOrderSvc
  • CompanySvc, ProjectSvc, LaborSvc, ReceiptSvc
  • PlantSvc, RegionSvc, ResourceSvc, SalesRepSvc
  • TermsSvc, UOMSvc, UserFileSvc, CarrierSvc
  • ContactSvc, CurrencySvc, GLAccountSvc, IndirectSvc

🚀 Usage

Starting the Server

Stdio Transport (Default)
npm start
HTTP Transport
npm run start:http
# Server runs on http://localhost:3000

Service Management

# List all available services
npm run services:list

# Enable a specific service
npm run services:enable CustomerSvc

# Disable a service
npm run services:disable TestSvc

# Add a new service
npm run services:add NewSvc "New Service Description" system

# Discover all services from Epicor API
npm run services:discover

# Convert cached services from Python server
npm run services:convert

🔧 Available Tools

The server provides four generic CRUD tools that work with any Epicor service:

1. Get - Retrieve Records

{
  "service": "CustomerSvc",
  "entity": "Customers",
  "filter": "City eq 'Sydney'",
  "select": "CustNum,Name,City",
  "top": 10
}

2. Post - Create Records

{
  "service": "CustomerSvc", 
  "entity": "Customers",
  "data": {
    "Name": "New Customer",
    "City": "Melbourne",
    "Country": "Australia"
  }
}

3. Patch - Update Records

{
  "service": "CustomerSvc",
  "entity": "Customers", 
  "key": {"Company": "FGA", "CustNum": 12345},
  "data": {
    "City": "Brisbane"
  }
}

4. Delete - Remove Records

{
  "service": "CustomerSvc",
  "entity": "Customers",
  "key": {"Company": "FGA", "CustNum": 12345}
}

📊 Service Categories

The 899 available services are organized into categories:

  • erp_bo: 897 services - Core Epicor ERP functionality
  • csfau_bo: 2 services - Custom Fujitsu General services
  • other: Additional services

Popular Service Examples:

  • Customer Management: Customer, CustomerPartXRef, CustBillTo, CustCnt
  • Inventory Management: Part, PartBin, PartClass, PartPlant, PartTran
  • Sales & Orders: SalesOrder, Quote, OrderDtl, OrderRel
  • Manufacturing: JobEntry, Labor, Resource, Plant, Project
  • Financial: GLAccount, Currency, SalesTax, BankAcct
  • Purchasing: PO, Vendor, Receipt, PurMisc

🔍 OData Query Support

All tools support OData query parameters:

  • $select: Specify fields to return
  • $filter: Filter results (e.g., City eq 'Sydney')
  • $orderby: Sort results (e.g., Name asc)
  • $top: Limit number of records
  • $skip: Skip records for pagination
  • $count: Include count in response

Example Queries:

# Get customers in Sydney, ordered by name
{
  "service": "CustomerSvc",
  "entity": "Customers",
  "filter": "City eq 'Sydney'",
  "orderby": "Name asc",
  "top": 50
}

# Get parts with specific part number pattern
{
  "service": "PartSvc", 
  "entity": "Parts",
  "filter": "startswith(PartNum, 'ABC')",
  "select": "PartNum,PartDescription,UnitPrice"
}

🏗️ Development

Building

npm run build

Type Checking

npm run typecheck

Development Mode

npm run dev

🔧 Generation Process

This MCP server was generated using the openapi-mcp-generator tool, which provides:

  • OpenAPI 3.0+ Support: Converts any OpenAPI specification into MCP-compatible servers
  • TypeScript Generation: Fully typed, maintainable TypeScript code output
  • Zod Validation: Automatic runtime input validation from OpenAPI definitions
  • Multiple Transports: Support for stdio, web (SSE), and StreamableHTTP transports
  • Authentication Support: API keys, Bearer tokens, Basic auth, and OAuth2
  • Proxy Behavior: Validates requests and proxies to original REST APIs

Key Features from openapi-mcp-generator:

  • 🔧 OpenAPI 3.0 Support: Converts any OpenAPI 3.0+ spec into an MCP-compatible server
  • 🔁 Proxy Behavior: Proxies calls to your original REST API while validating request structure and security
  • 🔐 Authentication Support: API keys, Bearer tokens, Basic auth, and OAuth2 supported via environment variables
  • 🧪 Zod Validation: Automatically generates Zod schemas from OpenAPI definitions for runtime input validation
  • ⚙️ Typed Server: Fully typed, maintainable TypeScript code output
  • 🔌 Multiple Transports: Communicate over stdio, SSE via Hono, or StreamableHTTP

For more information about the generation tool, visit: https://github.com/harsha-iiiv/openapi-mcp-generator

🧪 Testing

The project includes comprehensive tests organized in the /tests directory:

Running Tests

# MCP Protocol Tests
node tests/mcp/test_mcp.js
node tests/mcp/test_full_crud.js

# OData API Tests  
node tests/odata/test_epicor_odata.js
node tests/odata/test_direct_odata.js

# Authentication Tests
node tests/auth/test-comprehensive-auth.js
node tests/auth/test-focused-auth.js

# Integration Tests
node tests/integration/test_claude_request.js
node tests/integration/test-connectivity.js

Test Categories

  • MCP Tests - Server functionality and tool operations
  • OData Tests - Epicor API integration and data retrieval
  • Auth Tests - Authentication methods and security
  • Integration Tests - End-to-end functionality

See for detailed test documentation.

📁 Project Structure

epicor-unified-mcp/
├── src/
│   ├── index.ts              # Main server implementation
│   └── streamable-http.ts    # HTTP transport implementation
├── tests/                    # Test files organized by category
│   ├── mcp/                  # MCP protocol tests
│   ├── odata/                # OData API tests
│   ├── auth/                 # Authentication tests
│   ├── integration/          # Integration tests
│   └── README.md             # Test documentation
├── build/                    # Compiled JavaScript output
├── services-config.json      # Service configuration
├── manage-services.js        # Service management script
├── discover-services.js      # Service discovery script
├── convert-services.js       # Service conversion script
├── package.json             # Node.js dependencies and scripts
├── tsconfig.json            # TypeScript configuration
├── jest.config.js           # Jest test configuration
├── CONFIGURATION.md         # Detailed configuration guide
└── README.md                # This file

🔒 Security Considerations

  • API Keys: Store API keys securely in environment variables
  • Authentication: Uses Basic Auth + API Key authentication
  • HTTPS: Always use HTTPS in production environments
  • Network: Ensure proper network security for Epicor API access

🐛 Troubleshooting

Common Issues

  1. "Failed to load services config"

    • Ensure services-config.json exists and is valid JSON
    • Check file permissions

  2. "Service not available"

    • Verify the service is enabled in services-config.json
    • Check service name spelling

  3. Authentication Errors

    • Verify API key and credentials in .env file
    • Check Epicor system connectivity

  4. Build Errors

    • Ensure Node.js version >= 20.0.0
    • Run npm install to update dependencies

Debug Mode

Enable debug logging by setting:

DEBUG=epicor-mcp:*

📈 Performance

  • Concurrent Requests: Supports multiple concurrent API calls
  • Caching: Service configuration is cached for performance
  • Timeout: 30-second timeout for API requests
  • Memory: Optimized for production memory usage

🤝 Contributing

This project was generated using the openapi-mcp-generator tool. If you're interested in contributing to the underlying generation capabilities, please consider contributing to the original tool.

For this specific Epicor MCP server:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Acknowledgments

  • openapi-mcp-generator: The foundational tool that made this MCP server possible
  • Epicor ERP: The enterprise resource planning system this server integrates with
  • Model Context Protocol: The protocol specification that enables AI agent integration

📄 License

MIT License - see LICENSE file for details

🆘 Support

For issues and questions:

  • Check the for detailed setup
  • Review troubleshooting section above
  • Create an issue in the repository

🔄 Version History

  • v2.0.0: Unified server with 899 services support
  • v1.x: Initial implementation with limited services

Note: This server connects to Epicor ERP systems and can modify data. Always test in a development environment before using in production.