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 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:

{
  "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):

[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

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
rsr_sync_catalog / rsr_test_connection	RSR catalog sync / FTPS probe
fastbound_test_connection	FastBound API probe
atf_verify_ffl	EZ Check verify + upsert record (needs confirm=true)
firearms_in_stock	the Firearms In Stock report
find_item	typeahead item search
woo_test_connection	WooCommerce API probe
woo_push_item / woo_delist_item / woo_reconcile	list / delist / reconcile an Item on Woo (need confirm=true)
set_serial_title	set a per-gun Woo listing title (writes Serial No.item_name; takes effect on next push)

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.