QuickFile MCP Server

Model Context Protocol server for QuickFile UK accounting software - giving AI assistants full access to invoicing, clients, purchases, banking, and financial reporting.

Features

• 40+ MCP Tools for complete QuickFile API coverage
• Client Management: Create, search, update, delete clients and contacts
• Invoicing: Create invoices, estimates, credit notes; send by email; get PDF
• Purchases: Record and manage purchase invoices from suppliers
• Supplier Management: Full supplier CRUD operations
• Banking: Bank accounts, transactions, balances
• Financial Reports: Profit & Loss, Balance Sheet, VAT obligations, Ageing reports
• System Operations: Account details, event log, notes

Quick Start

1. Clone and Install

cd ~/git
git clone https://github.com/marcusquinn/quickfile-mcp.git
cd quickfile-mcp
npm install
npm run build

2. Configure Credentials

Create your QuickFile API credentials:

mkdir -p ~/.config/.quickfile-mcp
cat > ~/.config/.quickfile-mcp/credentials.json << 'EOF'
{
  "accountNumber": "YOUR_ACCOUNT_NUMBER",
  "apiKey": "YOUR_API_KEY",
  "applicationId": "YOUR_APPLICATION_ID"
}
EOF
chmod 600 ~/.config/.quickfile-mcp/credentials.json

Where to find these:

1. Account Number: Visible in top-right corner of QuickFile dashboard
2. API Key: Account Settings → 3rd Party Integrations → API Key
3. Application ID: Account Settings → Create a QuickFile App → copy the Application ID

3. Install OpenCode (if not already installed)

OpenCode is an open-source AI coding assistant that runs in your terminal. It supports MCP (Model Context Protocol) servers like this one.

# Install OpenCode globally
npm install -g opencode

# Or run directly with npx
npx opencode

See the OpenCode documentation for more installation options and configuration.

4. Configure OpenCode

Add to your ~/.config/opencode/opencode.json:

{
  "mcp": {
    "quickfile": {
      "type": "local",
      "command": ["node", "/path/to/quickfile-mcp/dist/index.js"],
      "enabled": true
    }
  }
}

Or use the setup script:

./setup.sh opencode

5. Start Using

Restart OpenCode and try:

"Show me my QuickFile account details"
"List my recent invoices"
"Search for clients named 'Smith'"
"Get the profit and loss report for this year"

Available Tools

System (3 tools)

Tool	Description
quickfile_system_get_account	Get account details (company, VAT status, year end)
quickfile_system_search_events	Search the audit event log
quickfile_system_create_note	Add notes to invoices, clients, etc.

Clients (7 tools)

Tool	Description
quickfile_client_search	Search clients by name, email, postcode
quickfile_client_get	Get full client details
quickfile_client_create	Create a new client
quickfile_client_update	Update client details
quickfile_client_delete	Delete a client
quickfile_client_insert_contacts	Add contacts to a client
quickfile_client_login_url	Get passwordless login URL for client portal

Invoices (8 tools)

Tool	Description
quickfile_invoice_search	Search invoices by type, client, date, status
quickfile_invoice_get	Get full invoice with line items
quickfile_invoice_create	Create invoice, estimate, or credit note
quickfile_invoice_delete	Delete an invoice
quickfile_invoice_send	Send invoice by email
quickfile_invoice_get_pdf	Get PDF download URL
quickfile_estimate_accept_decline	Accept or decline an estimate
quickfile_estimate_convert_to_invoice	Convert estimate to invoice

Purchases (4 tools)

Tool	Description
quickfile_purchase_search	Search purchase invoices
quickfile_purchase_get	Get purchase details
quickfile_purchase_create	Create purchase invoice
quickfile_purchase_delete	Delete purchase invoice

Suppliers (4 tools)

Tool	Description
quickfile_supplier_search	Search suppliers
quickfile_supplier_get	Get supplier details
quickfile_supplier_create	Create a new supplier
quickfile_supplier_delete	Delete a supplier

Banking (5 tools)

Tool	Description
quickfile_bank_get_accounts	List all bank accounts
quickfile_bank_get_balances	Get account balances
quickfile_bank_search	Search transactions
quickfile_bank_create_account	Create a bank account
quickfile_bank_create_transaction	Add bank transaction

Reports (6 tools)

Tool	Description
quickfile_report_profit_loss	Profit & Loss report
quickfile_report_balance_sheet	Balance Sheet report
quickfile_report_vat_obligations	VAT returns (filed & open)
quickfile_report_ageing	Debtor/Creditor ageing
quickfile_report_chart_of_accounts	List nominal codes
quickfile_report_subscriptions	Recurring subscriptions

API Rate Limits

QuickFile has a default limit of 1000 API calls per day per account. Contact QuickFile support if you need this increased.

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode (with auto-reload)
npm run dev

# Run unit tests (fast, no API calls)
npm test

# Run integration tests (requires credentials)
npm run test:integration

# Run all tests
npm run test:all

# Type check
npm run typecheck

# Lint
npm run lint

# Debug API calls (shows request/response with redacted credentials)
QUICKFILE_DEBUG=1 node dist/index.js

Testing with MCP Inspector

For development and debugging, use the official MCP Inspector tool instead of running through an AI assistant. This provides:

• Direct tool invocation - Call MCP tools directly with custom parameters
• Real-time response viewing - See full JSON responses without AI interpretation
• Faster iteration - No waiting for AI to process requests
• Debug visibility - View raw server output and errors

Quick Start

# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Run inspector with this server
npx @modelcontextprotocol/inspector node dist/index.js

Then open http://localhost:5173 in your browser to:

1. See all 37 available tools listed
2. Click a tool to view its input schema
3. Fill in parameters and execute
4. View the raw JSON response

Example Test Workflow

1. Test account access: Call quickfile_system_get_account with {}
2. Test client search: Call quickfile_client_search with {"companyName": "test"}
3. Test reports: Call quickfile_report_profit_loss with {"startDate": "2024-01-01", "endDate": "2024-12-31"}
4. Test invoice listing: Call quickfile_invoice_search with {"invoiceType": "INVOICE"}

This is the recommended approach for:

• Debugging API response issues
• Verifying new tools work correctly
• Testing parameter validation
• Investigating error responses

Contributing

QuickFile API Documentation

The QuickFile API has strict requirements for element ordering and required fields. When contributing:

1. Always check the official API schema at https://api.quickfile.co.uk/
2. Use Context7 for AI-assisted development: https://context7.com/websites/api_quickfile_co_uk
   • Context7 has indexed the full QuickFile API documentation
   • Use it to query exact field names, required parameters, and element ordering
   • Example: "What are the required fields for Purchase_Search?"

Key API Quirks

• Element ordering matters - XML schema validation requires specific field order
• Required fields vary by endpoint - OrderResultsBy and OrderDirection are required for most search endpoints
• Field naming is inconsistent - e.g., FromDate/ToDate vs DateFrom/DateTo
• SearchParameters wrapper - Most endpoints need this wrapper around query params
• NominalCode types - Sometimes string, sometimes int (check schema)

Response Structure Patterns

The API returns data in different structures depending on the endpoint:

Endpoint Type	Response Structure
Search (Client, Invoice, Supplier, Purchase)	{ RecordsetCount, ReturnCount, Record: [...] }
Bank_GetAccounts	{ BankAccounts: [...] } (direct array)
Bank_Search	{ Transactions: { Transaction: [...] } } (nested)
Ledger_GetNominalLedgers	{ Nominals: { Nominal: [...] } }
Report_Subscriptions	Requires noBody option (no Body element)
Report_VatObligations	Only for VAT-registered accounts with MTD

Debugging API Calls

Enable debug mode to see raw requests and responses:

QUICKFILE_DEBUG=1 node dist/index.js

This shows the full request/response with credentials redacted - essential for troubleshooting API issues.

Architecture

quickfile-mcp/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── api/
│   │   ├── auth.ts        # MD5 authentication
│   │   └── client.ts      # HTTP client
│   ├── tools/
│   │   ├── index.ts       # Tool registry & exports
│   │   ├── utils.ts       # Shared utilities (error handling, logging)
│   │   ├── schemas.ts     # Zod validation schemas
│   │   ├── system.ts      # System tools
│   │   ├── client.ts      # Client tools
│   │   ├── invoice.ts     # Invoice tools
│   │   ├── purchase.ts    # Purchase tools
│   │   ├── supplier.ts    # Supplier tools
│   │   ├── bank.ts        # Bank tools
│   │   └── report.ts      # Report tools
│   └── types/
│       └── quickfile.ts   # TypeScript types
├── tests/
│   ├── unit/              # Unit tests (201 tests)
│   └── integration/       # API integration tests (16 tests)
├── .agent/                # AI assistant documentation
└── .opencode/agent/       # OpenCode agent files

Credential Security

• Credentials stored in ~/.config/.quickfile-mcp/credentials.json
• File permissions should be 600 (owner read/write only)
• Never commit credentials to version control
• API key provides full access - treat it like a password
• Secretlint runs automatically on pre-commit to prevent accidental secret exposure
• Run npm run secretlint manually to scan for secrets

Related Projects

• OpenCode - Open-source AI coding assistant with MCP support
• QuickFile - UK accounting software
• QuickFile API Documentation
• Model Context Protocol - Protocol specification for AI tool integration
• AI DevOps Framework - Comprehensive AI infrastructure management

License

MIT License - see LICENSE file for details.

Created by Marcus Quinn - Copyright © 2025