kai751/freebird-mcp-server

Freebird MCP Server

Model Context Protocol (MCP) server for Dynamics GP via Freebird API

Connect Claude to your Microsoft Dynamics GP system through the Freebird REST API. This MCP server provides intelligent, AI-powered access to your ERP data including sales orders, customers, items, invoices, and more.

🚀 Quick Start

Installation (macOS)

1. Download and run the installer:

   • Double-click installer/Install Freebird MCP.app
   • Follow the prompts to enter your API credentials
   • The installer will configure Claude Desktop automatically

2. Restart Claude Desktop

3. Test the connection:

   Ask Claude: "What endpoints are available in the Freebird API?"
   

Manual Installation

1. Clone this repository:

   git clone https://github.com/YOUR_USERNAME/freebird-mcp-server.git
   cd freebird-mcp-server
   

2. Install dependencies:

   pip install mcp anthropic-mcp requests python-dotenv
   

3. Configure credentials: Create ~/.freebird_credentials:

   FREEBIRD_USERNAME=your_username
   FREEBIRD_PASSWORD=your_password
   FREEBIRD_APPLICATION_ID=your_app_id
   FREEBIRD_API_KEY=your_api_key
   USE_PRODUCTION=true
   

4. Add to Claude Desktop config: Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

   {
     "mcpServers": {
       "freebird": {
         "command": "python3",
         "args": ["/path/to/freebird-mcp-server/src/freebird_mcp_server.py"]
       }
     }
   }
   

5. Restart Claude Desktop

📋 Features

✅ Validated & Production-Ready

• 9 Working Filter Operators: eq, gt, gte, lt, lte, contains (validated 2025-11-26)
• 5 Date Fields: All tested and working with proper format
• Comprehensive Field Discovery: Automatic endpoint schema detection
• 698+ Q1 2024 Orders: Validated data availability
• Intelligent Defaults: Smart limit settings based on endpoint size

🔍 Available Tools

1. find_endpoint_by_data_need - Semantic search for relevant endpoints
2. get_endpoint_fields - Discover exact field names and types
3. query_any_endpoint - Query any Freebird API endpoint with filters

📊 Supported Endpoints

• /salesOrders - Sales orders and line items (171k+ records)
• /items - Product catalog (172k+ records)
• /customers - Customer master data (316 records)
• /invoices - Invoice data with line items
• /soShipments - Shipment tracking information
• /vendors - Vendor master data
• /purchaseOrders - Purchase orders
• And 50+ more endpoints!

📖 Usage Guide

Step 1: Find the Right Endpoint

Ask Claude: "I need to find recent sales orders from 2024"
→ Claude uses find_endpoint_by_data_need
→ Recommends: /salesOrders

Step 2: Discover Available Fields

Ask Claude: "What fields are available on /salesOrders?"
→ Claude uses get_endpoint_fields
→ Returns: orderDateUTC, documentId, customerId, etc.

Step 3: Query with Filters

Ask Claude: "Show me all orders from Q1 2024"
→ Claude uses query_any_endpoint with:
   filters="orderDateUTC_gte_1/1/2024,orderDateUTC_lte_3/31/2024"
→ Returns: 698 matching orders

🚨 Critical Requirements

Date Filtering - MUST READ

Date format MUST be M/D/YYYY (e.g., 1/1/2024, 12/31/2024)

NEVER use YYYY-MM-DD format - it causes string comparison bugs!

✅ Correct:

orderDateUTC_gte_1/1/2024,orderDateUTC_lte_3/31/2024

❌ Wrong:

orderDateUTC_gte_2024-01-01,orderDateUTC_lte_2024-03-31

Why: The API stores dates as M/D/YYYY H:MM:SS AM/PM. When you use YYYY-MM-DD format, it performs string comparison:

"7/3/3012" > "2024-01-01"  → TRUE (because '7' > '2')
Result: Year 3012 matches! 🚨

With M/D/YYYY format, date filtering works perfectly! ✅

Working Date Fields (All Validated)

All these fields work perfectly with M/D/YYYY format:

🔧 Filter Operators

✅ Validated Working Operators

Tested and confirmed on 2025-11-26:

❌ Confirmed Broken Operators

These return HTTP 400 errors:

• ne (not equal)
• startswith, endswith
• notnull_true, isnull_true
• in, notin (list operators)
• between (use gte + lte instead)

Combining Filters (AND Logic)

Use commas to combine multiple filters:

manufacturerName_eq_Cisco,itemListPriceUSD_gt_1000
→ Returns: Cisco items over $1000

📚 Common Query Patterns

Date Range (Q1 2024)

orderDateUTC_gte_1/1/2024,orderDateUTC_lte_3/31/2024

Price Range

itemListPriceUSD_gte_100,itemListPriceUSD_lte_1000

Active Customers

holdFlag_eq_0,inactiveFlag_eq_0

Recent Shipped Orders

actualShipDateUTC_gte_1/1/2024,deliveredFlag_eq_1

Cisco Parts Over $1000

manufacturerName_eq_Cisco,itemListPriceUSD_gt_1000

🗂️ Project Structure

freebird-mcp-server/
├── src/                          # Core MCP server code
│   ├── freebird_mcp_server.py   # Main MCP server
│   ├── freebird_client.py       # API client wrapper
│   └── gp_server_integration.py # Dynamics GP integration
├── scripts/                      # Testing & utility scripts
│   ├── test_freebird_filtering_slow.py
│   ├── diagnose_filter_behavior.py
│   ├── find_q1_2024_data.py
│   └── discover_endpoint_schemas.py
├── docs/                         # Documentation
│   ├── API_BUG_DATE_FILTERING_BROKEN.md
│   ├── CRITICAL_DATE_FORMAT_DISCOVERY.md
│   ├── DATE_FORMAT_BUG_FINAL.md
│   ├── Q1_2024_DATE_FILTERING_SOLVED.md
│   ├── FILTER_OPERATORS_FINAL.md
│   └── FILTER_QUICK_REFERENCE.md
├── data-mappings/               # Endpoint schemas
│   └── endpoint_schema_discovery.json
├── installer/                   # macOS installer
│   └── Install Freebird MCP.app
├── tests/                       # Test files
├── README.md                    # This file
├── LICENSE                      # MIT License
└── .gitignore                   # Git ignore rules

🧪 Testing

Run Filter Operator Tests

cd scripts
python3 test_freebird_filtering_slow.py

Diagnose Date Filtering Issues

python3 diagnose_filter_behavior.py

Find Q1 2024 Data Across All Date Fields

python3 find_q1_2024_data.py

Discover Endpoint Schemas

python3 discover_endpoint_schemas.py

📊 Data Availability

Q1 2024 Sales Orders: 698 Records

Validated on 2025-11-26 using:

orderDateUTC_gte_1/1/2024,orderDateUTC_lte_3/31/2024

Sample dates returned:

• 1/2/2024 11:00:00 PM
• 1/10/2024 11:00:00 PM
• 2/21/2024 11:00:00 PM
• 3/15/2024 11:00:00 PM

All dates are valid Q1 2024 ✅ No garbage dates (no year 3012, 2201, etc.) ✅

🔍 Troubleshooting

Issue: "Field 'X' not found"

Solution: Always call get_endpoint_fields first to discover exact field names.

Issue: Getting dates from year 3012 or wrong dates

Solution: Use M/D/YYYY format, NOT YYYY-MM-DD format.

Issue: No results returned

Solution:

1. Check field names are exact (case-sensitive)
2. Verify date format is M/D/YYYY
3. Remove filters one at a time to isolate the issue

Issue: HTTP 400 Error

Solution: You're using a broken operator (ne, startswith, endswith, etc.). Use only validated operators.

📝 API Quirks & Known Issues

1. Date Format Requirement

• MUST use M/D/YYYY (e.g., 1/1/2024)
• NEVER use YYYY-MM-DD (causes string comparison)

2. Broken Operators

• ne, startswith, endswith, notnull, isnull, in, notin, between all return 400 errors
• Use workarounds: gte+lte instead of between, filter client-side for ne

3. Boolean Flags

• Use string values "0" or "1"
• Example: holdFlag_eq_0 (not on hold)

4. Clean Fields

• Fields ending in Clean have special characters removed
• Example: itemMfgNumberClean for exact matching

5. Case Sensitivity

• Field names and values are case-sensitive
• Cisco ≠ cisco

🛠️ Development

Requirements

• Python 3.10+
• mcp package
• anthropic-mcp package
• requests package
• python-dotenv package

Running Locally

cd src
python3 freebird_mcp_server.py

Testing Filter Operators

cd scripts
python3 test_freebird_filtering_slow.py

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

Areas for Contribution

• Additional endpoint documentation
• More filter pattern examples
• Client-side filtering utilities
• Integration with other MCP servers

📄 License

MIT License - See file for details

🙏 Acknowledgments

• Built on the Model Context Protocol
• Powered by Anthropic Claude
• Integrates with Freebird API for Dynamics GP

📞 Support

For issues, questions, or feature requests:

1. Check the folder for detailed documentation
2. Review
3. Run diagnostic scripts in
4. Open an issue on GitHub

🎯 Quick Reference

Example Queries in Claude Desktop

Find recent orders:

Show me all sales orders from January 2024

Find expensive Cisco parts:

Show me Cisco items priced over $1000

Find active customers:

Show me all active customers (not on hold, not inactive)

Find shipped orders:

Show me all orders that shipped in Q1 2024

Analyze order data:

What's the average order value for Q1 2024?

Version: 1.0.0 Last Updated: 2025-11-26 Status: ✅ Production Ready