QuickFile MCP Server

Model Context Protocol server for

Features

• 37 MCP Tools across 7 categories 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

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

Or use the interactive setup script:

./setup.sh configure

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. Add to Your MCP Client

This server works with any MCP-compatible client. Add it to your client's configuration:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "quickfile": {
      "command": "node",
      "args": ["/path/to/quickfile-mcp/dist/index.js"]
    }
  }
}

Claude Code:

claude mcp add quickfile node /path/to/quickfile-mcp/dist/index.js

OpenCode (~/.config/opencode/opencode.json):

{
  "mcp": {
    "quickfile": {
      "type": "local",
      "command": ["node", "/path/to/quickfile-mcp/dist/index.js"],
      "enabled": true
    }
  }
}

4. Start Using

Restart your MCP client 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)

Development

npm install          # Install dependencies
npm run build        # Build TypeScript
npm run dev          # Development mode (auto-reload)
npm test             # Unit tests (no API calls)
npm run test:integration  # Integration tests (requires credentials)
npm run test:all     # All tests
npm run typecheck    # Type check
npm run lint         # Lint
npm run secretlint   # Scan for secrets

Enable debug mode to see raw API requests/responses (credentials redacted):

QUICKFILE_DEBUG=1 node dist/index.js

Testing with MCP Inspector

For development and debugging, use the official MCP Inspector to call tools directly without an AI client:

npx @modelcontextprotocol/inspector node dist/index.js

Then open http://localhost:5173 to browse all 37 tools, fill in parameters, and view raw JSON responses.

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 (3)
│   │   ├── client.ts      # Client tools (7)
│   │   ├── invoice.ts     # Invoice & estimate tools (8)
│   │   ├── purchase.ts    # Purchase tools (4)
│   │   ├── supplier.ts    # Supplier tools (4)
│   │   ├── bank.ts        # Bank tools (5)
│   │   └── report.ts      # Report tools (6)
│   └── types/
│       └── quickfile.ts   # TypeScript types
├── tests/
│   ├── unit/              # Unit tests (201 tests, ~96% coverage)
│   └── integration/       # API integration tests (19 tests)
├── .agents/               # AI assistant documentation (AGENTS.md)
└── .github/workflows/     # CI/CD (test, lint, build, release)

Contributing

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

3. Read AGENTS.md for API quirks, response structure patterns, and common workflows

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

API Rate Limits

QuickFile has a default limit of 1000 API calls per day per account. Contact QuickFile support if you need this increased.

Related Projects

• QuickFile - UK accounting software

• QuickFile API Documentation

• Model Context Protocol - Protocol specification for AI tool integration

• AI DevOps Framework - AI infrastructure management

License

MIT License - see LICENSE file for details.

Created by Marcus Quinn - Copyright 2025-2026