Quickfile MCP

🚀 QuickFile MCP Server

The Model Context Protocol server for QuickFile UK accounting software, enabling AI assistants to fully access invoicing, clients, purchases, banking, and financial reporting.

✨ Features

• Over 40 MCP Tools: Provide comprehensive coverage of the QuickFile API.
• Client Management: Create, search, update, and delete clients and contacts.
• Invoicing: Create invoices, estimates, and credit notes; send them via email; and obtain PDF versions.
• Purchases: Record and manage purchase invoices from suppliers.
• Supplier Management: Perform full CRUD operations on suppliers.
• Banking: Manage bank accounts, transactions, and balances.
• Financial Reports: Generate Profit & Loss, Balance Sheet, VAT obligations, and Ageing reports.
• System Operations: Access account details, event logs, and 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 the top-right corner of the QuickFile dashboard.
2. API Key: Navigate to Account Settings → 3rd Party Integrations → API Key.
3. Application ID: Go to 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 details.

4. Configure OpenCode

Add the following 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 the following commands:

"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 limit 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 tool provides:

• Direct tool invocation: Call MCP tools directly with custom parameters.
• Real-time response viewing: See full JSON responses without AI interpretation.
• Faster iteration: Eliminate the need to wait 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. View all 37 available tools.
2. Click a tool to view its input schema.
3. Fill in parameters and execute the tool.
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 approach is recommended for:

• Debugging API response issues.
• Verifying the correct functionality of new tools.
• 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).

🏗️ 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 are stored in ~/.config/.quickfile-mcp/credentials.json.
• File permissions should be set to 600 (owner read/write only).
• Never commit credentials to version control.
• The 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: An 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

This project is licensed under the MIT License - see the LICENSE file for details.

Created by Marcus Quinn - Copyright © 2025