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:
- Account Number: Visible in top-right corner of QuickFile dashboard
- API Key: Account Settings → 3rd Party Integrations → API Key
- 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:
- See all 37 available tools listed
- Click a tool to view its input schema
- Fill in parameters and execute
- View the raw JSON response
Example Test Workflow
- Test account access: Call
quickfile_system_get_accountwith{} - Test client search: Call
quickfile_client_searchwith{"companyName": "test"} - Test reports: Call
quickfile_report_profit_losswith{"startDate": "2024-01-01", "endDate": "2024-12-31"} - Test invoice listing: Call
quickfile_invoice_searchwith{"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:
- Always check the official API schema at https://api.quickfile.co.uk/
- 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 -
OrderResultsByandOrderDirectionare required for most search endpoints - Field naming is inconsistent - e.g.,
FromDate/ToDatevsDateFrom/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 secretlintmanually 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