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:

npm install -g @flinkest/mcp-server

Or use directly with npx (no installation required):

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

{
  "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)
2. Configure the bridge to connect to the Flinkest MCP server:

{
  "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
• Support: [email protected]

License

This project is licensed under the MIT License.