fulfil-mcp

MCP server for Fulfil.io ERP -- 29 tools for inventory management, order processing, shipment tracking, customer lookup, purchasing, returns, warehouse operations, and business analytics.

Built on the Model Context Protocol for seamless integration with Claude Desktop, Claude Code, and any MCP-compatible client. Connects to Fulfil.io's REST API v2 with automatic retries, exponential backoff, and rate-limit handling.

Tools (29)

Inventory (5 tools)

Orders (5 tools)

Shipments (2 tools)

Customers (2 tools)

Analytics (3 tools)

Purchasing (4 tools)

Returns (3 tools)

Warehouse (4 tools)

Operations (1 tool)

Related MCP server: cerebrochain-mcp-server

Quick Start

Install

git clone https://github.com/ExpertVagabond/fulfil-mcp.git
cd fulfil-mcp
npm install
npm run build

Configure Credentials

Set environment variables:

export FULFIL_API_KEY="your-fulfil-api-key"
export FULFIL_SUBDOMAIN="your-tenant-subdomain"

Or use credential files:

mkdir -p ~/.fulfil-mcp
echo "your-fulfil-api-key" > ~/.fulfil-mcp/api-key
echo "your-tenant-subdomain" > ~/.fulfil-mcp/subdomain
chmod 600 ~/.fulfil-mcp/*

Run

# Direct
FULFIL_API_KEY=xxx FULFIL_SUBDOMAIN=yyy node dist/index.js

# Via wrapper (reads from env or credential files)
./fulfil-mcp-wrapper.sh

Claude Desktop Configuration

Add to your Claude Desktop MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "fulfil": {
      "command": "node",
      "args": ["/path/to/fulfil-mcp/dist/index.js"],
      "env": {
        "FULFIL_API_KEY": "your-api-key",
        "FULFIL_SUBDOMAIN": "your-tenant"
      }
    }
  }
}

Claude Code Configuration

Add to ~/.mcp.json:

{
  "mcpServers": {
    "fulfil": {
      "command": "/path/to/fulfil-mcp/fulfil-mcp-wrapper.sh",
      "env": {
        "FULFIL_API_KEY": "your-api-key",
        "FULFIL_SUBDOMAIN": "your-tenant"
      }
    }
  }
}

Usage Examples

Once connected, ask Claude natural-language questions and it will call the appropriate tools:

Inventory

"Which products are below 10 units in stock?" "Show me the stock breakdown for product 4521 across all warehouses."

Orders

"List all orders from the last 7 days that haven't shipped yet." "Get the full details for order 18923."

Operations

"Give me the daily ops briefing." "Are there any shipment exceptions I should know about?"

Purchasing

"Show overdue purchase orders from our suppliers." "Create a draft PO for supplier 312 with 500 units of product 891."

Analytics

"What were our top 10 products by revenue last month?" "Generate a sales summary for Q4 2025."

Returns

"What's our return rate for the past 90 days?" "Which products have the highest return rates?"

Warehouse

"List all warehouses and their utilization." "Generate a pick list for the main warehouse."

Architecture

src/
  index.ts              MCP server setup + 29 tool registrations
  api.ts                Fulfil.io REST client (retries, rate-limits, backoff)
  tools/
    inventory.ts        Product search, stock levels, low stock alerts
    orders.ts           Sales orders, fulfillment status, delayed orders
    shipments.ts        Outbound shipments, exceptions
    customers.ts        Customer search, order history
    analytics.ts        Sales summaries, top products, valuations
    operations.ts       Daily ops briefing
    purchasing.ts       Purchase orders, overdue POs, draft creation
    returns.ts          Returns, return rate reports
    warehouse.ts        Warehouse listing, utilization, receipts, pick lists

API Client

The FulfilClient class handles all communication with the Fulfil.io REST API v2:

• Automatic retries with exponential backoff on 5xx errors and network failures

• Rate-limit handling with Retry-After header support

• Tryton-style domain filters for flexible record queries

• Singleton pattern -- one client instance per server lifecycle

Fulfil.io API Reference

Key models: product.product, product.template, sale.sale, sale.line, stock.shipment.out, stock.shipment.in, stock.move, stock.location, party.party, purchase.purchase, purchase.line

Development

# Watch mode (recompile on change)
npm run dev

# Build
npm run build

# Run
npm start

Requirements

• Node.js >= 18

• TypeScript 5.3+

• A Fulfil.io account with API access

Contributing

Contributions are welcome. To add a new tool:

1. Create or extend a file in src/tools/ with the tool implementation

2. Export the handler function from that file

3. Register the tool in src/index.ts with a Zod schema and description

4. Run npm run build to verify compilation

5. Open a pull request

Please keep tool descriptions clear and specific -- they serve as documentation for both humans and AI models.

License

MIT