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