Invoice Search MCP Server

A Model Context Protocol (MCP) server that enables Claude to search for invoices by reference number.

Features

• Two search modes:
  • Quick summary lookup: minimal data (~150 bytes)
  • Full invoice details: complete data including line items (~2-10KB)
• Health check and statistics tools
• Cloudflare Access authentication support
• Configurable API endpoint
• Simple JSON response format
• Built with TypeScript for type safety

Prerequisites

• Node.js 18 or higher
• Access to an invoice API endpoint
• Cloudflare Access credentials (Client ID and Secret)

Installation

1. Clone this repository:

git clone https://github.com/your-org/freeagent-mcp-invoice-search.git
cd freeagent-mcp-invoice-search

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Environment Variables

Create a .env file or set the following environment variables:

• INVOICE_API_URL (required): Base URL of your invoice API
• CF_ACCESS_CLIENT_ID (required): Cloudflare Access Client ID
• CF_ACCESS_CLIENT_SECRET (required): Cloudflare Access Client Secret

MCP Settings

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "invoice-search": {
      "command": "node",
      "args": ["/absolute/path/to/freeagent-mcp-invoice-search/build/index.js"],
      "env": {
        "INVOICE_API_URL": "https://your-invoice-api.com",
        "CF_ACCESS_CLIENT_ID": "your-cloudflare-client-id",
        "CF_ACCESS_CLIENT_SECRET": "your-cloudflare-client-secret"
      }
    }
  }
}

Usage

Once configured, Claude can search invoices using natural language:

• "Get a summary of invoice INV-011"
• "Show me the full details for invoice 100056"
• "Look up invoice INV145001"

Tool: get_invoice_summary

Quick lookup returning minimal data for fast reference verification.

Parameters:

• reference (string, required): The invoice reference number

Response (~150 bytes):

{
  "invoices": [
    {
      "id": 123,
      "url": "https://api.freeagent.com/v2/invoices/123",
      "reference": "INV-011"
    }
  ],
  "count": 1,
  "limit": 50,
  "offset": 0
}

Tool: get_invoice_full_details

Complete invoice information including all fields and line items.

Parameters:

• reference (string, required): The invoice reference number

Response (~2-10KB):

{
  "invoices": [
    {
      "id": 123,
      "reference": "INV-011",
      "url": "https://api.freeagent.com/v2/invoices/123",
      "customer_name": "Acme Corp",
      "amount": 1500.00,
      "currency": "GBP",
      "status": "paid",
      "created_at": "2024-01-15",
      "line_items": [...]
    }
  ],
  "count": 1,
  "limit": 50,
  "offset": 0
}

Other Tools

• check_health: Check API health and database connection status
• get_stats: Get invoice cache statistics (totals, date ranges, status breakdown)

API Requirements

Your invoice API must:

• Accept GET requests to /api/invoices
• Support reference query parameter (string, required)
• Support include_full_invoice query parameter (boolean, optional)
  • When false or omitted: return minimal data (id, url, reference)
  • When true: return full invoice JSON with all fields
• Support Cloudflare Access authentication via headers
• Return JSON in the format shown above

Development

Build

Compile TypeScript to JavaScript:

npm run build

Watch Mode

Automatically rebuild on file changes:

npm run watch

Debugging

The server logs diagnostic information to stderr. You can view these logs in your terminal or MCP client:

# Run server directly to see logs
export INVOICE_API_URL="https://your-api.com"
export CF_ACCESS_CLIENT_ID="your-client-id"
export CF_ACCESS_CLIENT_SECRET="your-client-secret"
node build/index.js

Project Structure

freeagent-mcp-invoice-search/
├── src/
│   ├── types.ts              # TypeScript interfaces
│   ├── mcp-client.ts         # HTTP client
│   └── index.ts              # MCP server
├── build/                    # Compiled JavaScript (generated)
├── .env.example              # Environment variable template
├── CLAUDE.md                 # AI context documentation
├── README.md                 # This file
├── package.json              # NPM configuration
└── tsconfig.json             # TypeScript configuration

Troubleshooting

Server won't start

• Check that all required environment variables are set
• Verify Node.js version is 18 or higher: node --version
• Check file permissions on build/index.js
• Review error messages in console output

No results found

• Verify the invoice reference exists in your system
• Check API credentials are correct
• Review server logs for API errors
• Test API endpoint directly with curl:

  curl -H "CF-Access-Client-Id: your-client-id" \
       -H "CF-Access-Client-Secret: your-client-secret" \
       "https://your-api.com/api/invoices?reference=INV-011"

Authentication errors

• Confirm CF_ACCESS_CLIENT_ID is valid
• Confirm CF_ACCESS_CLIENT_SECRET is valid
• Check API endpoint is accessible from your network
• Verify Cloudflare Access is properly configured on the API

MCP Integration Issues

• Verify build/index.js exists after running npm run build
• Check MCP settings JSON is valid
• Restart Claude Desktop after configuration changes
• Review Claude Desktop logs for connection errors

Technical Details

Architecture

The server follows a three-layer architecture:

1. Types Layer (types.ts): TypeScript interfaces for type safety
2. Client Layer (mcp-client.ts): HTTP client with axios for API communication
3. Server Layer (index.ts): MCP protocol implementation and tool registration

Error Handling

• Input validation with clear error messages
• HTTP errors include status codes
• All errors logged to stderr with context
• Graceful handling of API timeouts (30 second timeout)

Logging

All logs use stderr (stdout is reserved for MCP protocol):

• [InvoiceCache] prefix for HTTP client logs
• [InvoiceSearch] prefix for server logs
• Structured logging with context objects

License

MIT

Contributing

Contributions are welcome! Please open an issue or pull request.

Related Projects

• freeagent-mcp - Reference MCP server implementation
• freeagent-invoice-cache - Invoice cache API

Support

For issues and questions:

• Open an issue on GitHub
• Check CLAUDE.md for detailed architecture documentation
• Review the troubleshooting section above