GunStore-POS Admin MCP

A local MCP server that wraps the GunStore-POS Frappe REST API, so you can read and change production settings/content from Claude or Codex — toggle integration config, edit item pricing/listing, fix records, trigger RSR/FastBound/ATF operations, run the Firearms-In-Stock report.

Companion repo: firearm-listing-import — a Claude Code / Codex skill that uses this MCP (per-gun photos + descriptions → Serial No → WooCommerce). Extracted from the gunstore-pos app as a standalone, separately distributable package.

How it works

A small generic backbone (frappe_* tools) covers every doctype and every

whitelisted method — present and future. A curated layer makes the frequent settings/sync/report ops one call.

Talks to Frappe over HTTPS with token auth (Authorization: token key:secret).
Safety: delete/cancel/submit and destructive methods — including this

domain's own high-consequence verbs (dispose / push / charge / consolidate / ship / return / receive / sold / settle / onboard) — require confirm=true; password/credential fields are never transmitted (set those in Desk); schema/permission doctypes are read-only.

Setup

1. Generate a Frappe API key

In Desk as the user you want to act as (Administrator): top-right avatar → My Settings → API Access → Generate Keys. Copy the API Key and API Secret (the secret is shown only once).

2. Configure credentials

cp .env.example .env
# edit .env: FRAPPE_BASE_URL, FRAPPE_API_KEY, FRAPPE_API_SECRET

.env is git-ignored. Point at dev first (http://dev.localhost:8000) to test, then switch to prod (https://pos.oldsteelarsenal.com).

3. Install

uv sync          # creates .venv and installs deps

4. Register with your agent

/path/to/gunstore-pos-mcp below is wherever you cloned this repo (the package is at the repo root). The server loads .env by its own file path, so credentials never go in the agent config.

Claude Code — add to .mcp.json (project) or run claude mcp add: ``json { "mcpServers": { "gunstore-pos": { "command": "uv", "args": ["run", "--directory", "/path/to/gunstore-pos-mcp", "gunstore-mcp"] } } } ` Claude Desktop — the same block in claude_desktop_config.json`.

Codex — add to ~/.codex/config.toml, then restart Codex (it reads MCP servers at startup): ``toml [mcp_servers.gunstore-pos] command = "uv" # or an absolute path to uv if it isn't on Codex's PATH args = ["run", "--directory", "/path/to/gunstore-pos-mcp", "gunstore-mcp"] startup_timeout_sec = 120 ` Verify with a quick stdio handshake (initialize + tools/list`) or just list tools from within Codex.

Secrets stay in .env (loaded by the server), not in the agent config.

Tools

中文速查手册（按"你想干什么"组织，含安全须知与替代路径）：TOOLS.md

79 tools total: 10 generic + 53 curated + 11 distributor + 5 CPA reports; 75 register by default — the 4 distributor queue actions are opt-in via GUNSTORE_MCP_DISTRIBUTOR_ACTIONS=1 (they are not registered otherwise).

Modes: GUNSTORE_MCP_MODE=cpa starts a read-only accountant surface — exactly 18 tools (the write surface is never registered), a per-name read-only method allowlist at the client layer, and the 7 integration Settings doctypes blocked from reads. Default (full) is the whole surface. Register a second server entry (e.g. gunstore-pos-cpa) with the same command plus "env": {"GUNSTORE_MCP_MODE": "cpa"} to run both side by side.

Standalone CPA install

To install only the read-only accountant surface (no full server) — e.g. on a second machine or for an analyst agent:

git clone git@github.com:xuanji86/gunstore-pos-mcp.git ~/gunstore-pos-mcp
claude mcp add gunstore-pos-cpa --scope user \
  --env GUNSTORE_MCP_MODE=cpa \
  --env FRAPPE_BASE_URL=https://pos.example.com \
  --env FRAPPE_API_KEY=<key> \
  --env FRAPPE_API_SECRET=<secret> \
  -- uv run --directory ~/gunstore-pos-mcp gunstore-mcp

Process env beats .env: the server loads .env with override=False,

so env vars set in the registration win. A standalone install needs no .env file at all — and the same checkout can serve several entries with different FRAPPE_BASE_URL / mode combinations (e.g. a dev-site instance).

Verify: after connecting, tools/list must show exactly 18 tools and

the server name gunstore-pos-cpa. A misspelled/unknown mode value refuses to start (fail-closed) rather than silently degrading to the writable surface.

Security boundary — read before handing this to a third party: the

three-layer gate restricts the MCP call layer only. The API key/secret in the registration is whatever that Frappe user can do — with a System Manager key, anyone who extracts it can write via plain REST, MCP gate or not. For a third-party (e.g. an outside accountant's machine), create a dedicated Frappe API user with read-only roles and register with that key pair.

Generic backbone

| Tool | Purpose | |---|---| | frappe_list_documents | list any doctype (filters / fields / limit; limit=0 = all) | | frappe_get_document | fetch one doc (Single: name == doctype) | | frappe_describe_doctype | fields incl. custom fields; flags password fields | | frappe_create_document | create (credential fields stripped) | | frappe_update_document | update (credential fields stripped) | | frappe_delete_document | delete — needs confirm=true | | frappe_submit_document | submit a draft — needs confirm=true | | frappe_cancel_document | cancel a submitted doc — needs confirm=true | | frappe_run_method | call any whitelisted method by dotted path | | frappe_run_report | run a Script/Query report |

Curated

| Tool | Purpose | |---|---| | get_settings / update_settings | ffl \| fastbound \| rsr \| payroc \| woocommerce \| dealer \| shipstation | | find_item / item_stock / available_serials | typeahead item search / stock per item / in-stock serials + per-gun prices | | firearms_in_stock | the Firearms In Stock report | | receive_goods | Purchase Receipt + FFL acquisitions + FastBound push (confirm) | | add_stock / set_stock | non-serialized stock add / absolute set (confirm) | | toggle_service_need | gunsmith flag on a Serial No (confirm) | | rsr_catalog_search / rsr_sync_catalog / rsr_test_connection | RSR catalog search / full sync / FTPS probe | | promote_to_item / backfill_from_rsr | RSR catalog row → sellable Item / backfill Item fields (confirm) | | fastbound_test_connection / push_serial_to_fastbound / boundbook_reconcile | FB probe / per-gun correction push (confirm) / bound-book reconcile (apply needs confirm) | | atf_verify_ffl / verify_supplier_ffl / reverify_all_ffls | ATF eZ-Check verifies (confirm) | | woo_test_connection / woo_push_item / woo_delist_item / woo_reconcile | store probe / list / delist / reconcile an Item — all take site: retail\|dealer (writes need confirm) | | woo_push_serial / woo_delist_serial | list / delist ONE gun (SKU item_code::serial; site; confirm) | | set_serial_title | per-gun Woo listing title (writes Serial No.item_name; takes effect on next push) | | pending_orders / pending_web_orders | the Pending Order queue: counter/dealer rows + paid web orders (read-only; consignments live in consignment_queue) | | dispose_order / dispose_web_order | book the FFL transfer dispositions — stock-out + FastBound push (confirm) | | record_payment | Payment Entry against an unpaid submitted invoice; Zelle needs transaction_number (confirm) | | cancel_order | cancel a submitted counter/dealer order — cascades disposition/stock/FastBound/ShipStation reversal + refund (confirm + reason) | | push_shipment / mark_shipped_manually / shipstation_test_connection | ShipStation label push (confirm) / no-push escape hatch (confirm) / probe | | consignment_queue / consignment_dealers / consignment_serials / consignment_dealer_orders | outbound-consignment reads: At-Dealer queue / shippable FFL dealers / pickable serials / settlement queue | | create_consignment_out / ship_consignment_out / push_consignment_shipment / mark_consignment_shipped | build / dispose+ship / ShipStation push / manual-ship w/ tracking (confirm) | | retry_consignment_invoice / return_consignment_lines / cancel_consignment | settlement-invoice retry / take unsold guns back / cancel line-or-draft (confirm; cancel needs reason) | | start_4473 / manager_override_4473 / start_transfer_4473 | 4473 kickoff / stuck-sale manager override / customer transfer (confirm) | | upload_attachment | multipart file upload → File doc, optionally attached to a doctype+name / Attach field |

CPA reports (read-only; registered in both modes)

| Tool | Purpose | |---|---| | sales_report | the POS Sales Report, payload passed through unchanged (views Order / Order Detail / Product; channel POS/Web/B2B-Manual) | | gl_entries | GL rows for a date range (is_cancelled=0 always; explicit truncated:true) | | financial_statement | P&L / Balance Sheet (Date Range) / Trial Balance (fiscal-year auto-resolved) | | tax_liability | sales-tax liability roll-forward from the GL — accounts resolved from the default sales-tax template, vouchers bucketed fail-closed, cent-exact identity asserted | | ar_ap_summary | aged AR / AP as of a date (Posting Date basis, 30/60/90/120) |

Security notes

Uses the key's user (Administrator) = full access. Run locally only; keep

.env out of git (it is, by default).

Credentials never transit the MCP: password-type and credential-named fields are

stripped from every write. Set secrets in Desk directly.

All writes are logged by Frappe under the key's user (audit trail).
To revoke access, regenerate that user's keys in Desk.

GunStore-POS Admin MCP