QuickFile MCP Server

Model Context Protocol server for

License: MIT Version Quality Gate Status Codacy Badge Maintainability CodeFactor CodeRabbit Pull Request Reviews MCP AGENTS.md QuickFile TypeScript Node.js

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_account with {}
Test client search: Call quickfile_client_search with {"companyName": "test"}
Test reports: Call quickfile_report_profit_loss with {"startDate": "2024-01-01", "endDate": "2024-12-31"}
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:

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 - 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)

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.

QuickFile MCP Server

QuickFile MCP Server

Features

Quick Start

1. Clone and Install

2. Configure Credentials

3. Install OpenCode (if not already installed)

4. Configure OpenCode

5. Start Using

Available Tools

System (3 tools)

Clients (7 tools)

Invoices (8 tools)

Purchases (4 tools)

Suppliers (4 tools)

Banking (5 tools)

Reports (6 tools)

API Rate Limits

Development

Testing with MCP Inspector

Quick Start

Example Test Workflow

Contributing

QuickFile API Documentation

Key API Quirks

Architecture

Credential Security

Related Projects

License

Resources

New MCP Servers

Latest Blog Posts

MCP directory API