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)

Clients (7 tools)

Invoices (8 tools)

Purchases (4 tools)

Suppliers (4 tools)

Banking (5 tools)

Reports (6 tools)

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:

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