npm package: @flinkest/mcp-server
Description: Model Context Protocol server for Flinkest ERP - Access customer, supplier, document and invoice data through AI assistants
Author: Flinkest
Latest version: 1.6.0

# Flinkest MCP Server

A Model Context Protocol (MCP) server that provides access to Flinkest ERP data through AI applications like Claude Desktop.

## Features

- **Customer Data Access**: Retrieve customer information with flexible filtering
- **Supplier Data Access**: Retrieve supplier information with flexible filtering
- **Document Management Access**: Complete access to all business documents (offers, invoices, delivery notes, etc.)
- **Invoice Data Access**: Access invoice data with automatic line item inclusion
- **Product Data Access**: Search and filter products with detailed information
- **Stock Location Data Access**: Access stock locations and warehouse information
- **Work Report Data Access**: Comprehensive work reports with times, products, and billing details
- **Product Stock Movement Tracking**: Monitor inventory in/out transactions with batch tracking
- **Receipt Items Analysis**: Detailed line-item access across all document types
- **Location Management**: Access to customer/supplier location data with GPS coordinates

## Installation

Install the MCP server globally via npm:

```bash
npm install -g @flinkest/mcp-server
```

Or use directly with npx (no installation required):

```bash
npx @flinkest/mcp-server
```

## Configuration

### Claude Desktop Setup

Add the following to your Claude Desktop configuration file:

**Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "flinkest": {
      "command": "npx",
      "args": ["@flinkest/mcp-server"],
      "env": {
        "FLINKEST_API_TOKEN": "your_api_token_here",
        "FLINKEST_SITE_ALIAS": "your_site_alias"
      }
    }
  }
}
```

### OpenAI / ChatGPT Setup

For OpenAI-compatible clients that support MCP (via MCP bridge tools):

1. Install the MCP-to-OpenAI bridge (e.g., [mcp-bridge](https://github.com/modelcontextprotocol/mcp-bridge))
2. Configure the bridge to connect to the Flinkest MCP server:

```json
{
  "servers": {
    "flinkest": {
      "command": "npx",
      "args": ["@flinkest/mcp-server"],
      "env": {
        "FLINKEST_API_TOKEN": "your_api_token_here",
        "FLINKEST_SITE_ALIAS": "your_site_alias"
      }
    }
  }
}
```

3. Connect your OpenAI client to the MCP bridge endpoint

**Note**: Direct MCP support in ChatGPT is not yet available. Use MCP bridge tools or wait for official OpenAI MCP integration.

### Environment Variables

- **FLINKEST_API_TOKEN** (required): Your Flinkest API token
- **FLINKEST_SITE_ALIAS** (required): Your Flinkest site alias (e.g., "mycompany")

### Getting Your API Credentials

1. Log in to your Flinkest account
2. Navigate to Settings → Users
3. Generate a new Secret
4. Your site alias is the subdomain of your Flinkest URL (e.g., "mycompany" from "mycompany.flinkest.app")

## Available Tools

### 1. get_customers

Retrieve customer data from Flinkest ERP.

### 2. get_suppliers

Retrieve supplier data from Flinkest ERP.

### 3. get_invoices

Retrieve invoice data from Flinkest ERP.

### 4. get_products

Retrieve product data from Flinkest ERP.

### 5. get_stocks

Retrieve stock location data from Flinkest ERP.

### 6. get_workreports

Retrieve work report data from Flinkest ERP - comprehensive service documentation with work times, used products, vehicle usage, and billing information.

### 7. get_offers

Retrieve offer documents from Flinkest ERP.

### 8. get_costestimates

Retrieve cost estimate documents from Flinkest ERP.

### 9. get_orderconfirmations

Retrieve order confirmation documents from Flinkest ERP.

### 10. get_deliverynotes

Retrieve delivery note documents from Flinkest ERP.

### 11. get_invoices_receipts

Retrieve invoice documents from Flinkest ERP (document-based access).

### 12. get_credits

Retrieve credit note documents from Flinkest ERP.

### 13. get_productstocks

Track product stock movements (inventory in/out transactions) with detailed filtering by product, location, supplier, and batch information.

### 14. get_offer_receipts

Retrieve offer/quotation documents with automatic receiptitems inclusion.

### 15. get_credit_receipts

Retrieve credit note documents with automatic receiptitems inclusion.

### 16. get_deliverynote_receipts

Retrieve delivery note documents with automatic receiptitems inclusion.

### 17. get_receiptitems

**Advanced Line Item Analysis** - Dedicated tool for analyzing receipt items (invoice/offer/delivery note line items) across all document types. Better performance than expanding receiptitems in document queries.

### 18. get_contact_locations

**Location Management** - Access customer/supplier locations with detailed address information, GPS coordinates, and geographic filtering capabilities.

## Data Access Patterns

### When to Use Expand vs. Separate Tools

**Use Expand Parameters** when:
- You need parent object + related data in a single query
- Working with smaller datasets
- Simple relationship access

**Use Separate Tools** when:
- Analyzing sub-entities across multiple parent objects
- Need advanced filtering on sub-entity fields
- Working with large datasets
- Performance is critical

**Examples:**
```
# Good for expand
"Get invoices with customer data" → use get_invoices with expand: "contact"

# Better with separate tool
"Analyze all line items with discounts > 10%" → use get_receiptitems
"Find customer locations in Berlin" → use get_contact_locations
```

## Quick Start Example

Once configured, you can ask Claude:

**Basic Data Queries:**
- "Get all customers from Berlin"
- "Show all suppliers from Hamburg"
- "Show me unpaid invoices over €500"
- "Find invoices from last 30 days"
- "Show all products under €100"
- "List all warehouse locations"

**Advanced Analytics with New Tools:**
- "Analyze all line items with discounts over 10%" (uses get_receiptitems)
- "Find customer locations in Berlin with GPS coordinates" (uses get_contact_locations)
- "Track inventory movements for product XYZ" (uses get_productstocks)
- "Show stock in/out transactions with batch numbers"
- "Find all receipt items for product category ABC"
- "List customer delivery addresses by city"

**Document Management:**
- "Show all offers from this month"
- "List delivery notes for customer ACME Corp"
- "Find cost estimates with amounts over €5000"
- "Get all draft invoices awaiting approval"
- "Show completed delivery notes with serial numbers"

**Work Reports & Projects:**
- "Show work reports from last month with working hours"
- "Find completed work reports for project X"
- "List work reports by employee with time details"
- "Show work reports with used products and billing"

## Error Handling

The server includes comprehensive error handling:

- Invalid API credentials
- Network errors
- Invalid filter parameters
- Rate limiting
- API response errors

All errors are returned in a structured format with detailed error messages.

## Troubleshooting

### Common Issues

**"Missing required environment variables"**
- Ensure both `FLINKEST_API_TOKEN` and `FLINKEST_SITE_ALIAS` are set in your Claude Desktop configuration

**"Failed to fetch data from Flinkest API"**
- Verify your API token is valid and has not expired
- Check that your site alias is correct
- Ensure your Flinkest account has API access enabled

**Claude Desktop doesn't recognize the server**
- Restart Claude Desktop after updating the configuration
- Check the configuration file path is correct for your OS
- Verify the JSON syntax in your configuration file

## Support

- **Documentation**: [https://www.flinkest.io](https://docs.flinkest.app)
- **Support**: support@flinkest.app


## License

This project is licensed under the MIT License.