simpleshop-mcp

SimpleShop MCP

Read-only FastMCP server for SimpleShop accounting data.

This server exposes a small MCP tool surface for AI agents that need to audit SimpleShop documents, download document PDFs, inspect products, and review product sales exports before copying data into another accounting system.

It is intentionally read-only. It does not create, update, delete, pay, cancel, send, or mutate SimpleShop records.

Install as a Plugin

simpleshop-mcp ships as a Claude Code / Cowork plugin. In either client:

/plugin marketplace add mikz/simpleshop-mcp
/plugin install simpleshop-mcp@simpleshop-mcp

The server starts without credentials. To sign in, call the simpleshop_login MCP tool. It supports mode: "auto" | "direct" | "prefab" | "web": Apps-capable clients get an inline Prefab form, and other clients can use mode: "direct" with email and api_key in the tool call or a localhost web form. The server validates credentials against SimpleShop, persists them locally, and updates the running MCP server.

Requirements on the host machine:

• uvx on PATH (install with uv)
• Python 3.13 (uvx will fetch one if missing)

Features

• Find SimpleShop documents across invoices, proformas, receipts, orders, tax documents, and related document types.
• Default document search is payment-reconciliation oriented: invoices, advance invoices, proformas, payment requests, tax documents, and receipts. Orders are explicit because they often duplicate invoice payment keys.
• Batch-download document PDFs, with per-document success/error results.
• Find products through the SimpleShop product API.
• Fetch and normalize SimpleShop "who bought" product sales exports.
• Return metadata useful for accounting filters, including document types, product types, flags, payment methods, number series, and tags.
• Use one reusable HTTP client initialized through FastMCP lifespan dependency injection.
• Redact customer/buyer PII by default, with explicit opt-in for full data.

Tool Surface

simpleshop_login
simpleshop_test_login
simpleshop_find_documents
simpleshop_download_documents
simpleshop_find_products
simpleshop_get_product_sales
simpleshop_get_metadata

simpleshop_login collects and validates credentials at runtime through direct arguments, Prefab UI, or a localhost web form. simpleshop_test_login takes no arguments and is the quickest way to confirm the current credentials work. It reports not_logged_in when none are available.

Finder tools use a concrete query object with a required mode field:

{
  "query": {
    "mode": "search"
  }
}

or:

{
  "query": {
    "mode": "by_ids",
    "ids": [123]
  }
}

by_ids mode requires IDs and ignores stray search filters so retry calls remain robust when an agent carries over defaults from schema discovery. For simpleshop_find_documents, omitting document_types defaults to settlement/accounting documents used for payment reconciliation. Pass document_types: ["order"] explicitly for order workflows. Paid-date search uses paid_from and paid_to, which map to SimpleShop's date_paid filter expression; pass the same date to both fields for an exact paid day. Document results include normalized payment_instructions for intended receiving-account details and document paid state. They do not include matched bank transaction evidence.

See TOOLS.md for full schemas, examples, cursor behavior, and privacy controls. The design rationale is in DESIGN.md.

Privacy Defaults

Normal document and sales responses redact customer/buyer PII by default.

Set include_customer_pii: true only when the caller actually needs names, emails, phone numbers, addresses, company IDs, VAT IDs, custom sales fields, raw document payloads, or raw CSV exports.

Raw fields are guarded:

• include_raw requires include_customer_pii: true.
• include_raw_csv requires include_customer_pii: true.
• simpleshop_get_product_sales supports max_sales_rows, total_rows, returned_rows, and truncated for bounded exports.
• Public money values are returned as fixed two-decimal strings. When payment instruction account fields are present, they are normalized under payment_instructions.

Requirements

• Python >=3.13,<3.14
• uv
• Optional: mise for pinned local tool versions

The project currently pins:

• fastmcp[apps]==3.3.0
• httpx==0.28.1
• keyring>=25.0,<26
• pydantic==2.13.4
• pydantic-settings==2.14.1

Installation

Using mise:

mise install
mise run sync

Using uv directly:

uv sync --locked

Login And Configuration