1c Fresh Mcp

1c-fresh-mcp

MCP server for 1C:Fresh (Russian cloud accounting). Lets AI agents (Claude, Cursor, or any MCP client) talk to cloud 1C via its standard OData REST API. Works around the known OData 1C:Fresh limitations (INN filter, $expand=Товары, tabular sections), accounts for the 22 % VAT (in force since 2025), and keeps document times in the server's timezone.

Ships with an optional PDF renderer for the «Счёт на оплату» (invoice for payment) printable form.

🇷🇺 Русская версия → [README.ru.md](README.ru.md)

---

Features

• Catalogs: counterparties, products/services, organizations, bank payments.
• Documents: outgoing invoices (СчетНаОплатуПокупателю), sales (РеализацияТоваровУслуг) — create, read (incl. tabular section), post, unpost, mark for deletion.
• Address handling: counterparty address uses the correct Вид_Key = ЮрАдресКонтрагента so it lands in the printable form (1C:Fresh silently drops it otherwise).
• One-shot invoice POST: the tabular section Товары goes inside the document body (1C:Fresh returns 400 on POST and 405 on PATCH to _Товары).
• INN lookup: get_counterparty_by_inn works around the HTTP 500 that 1C:Fresh returns on $filter=ИНН eq '…' by fetching the list and filtering client-side.
• PDF invoice: standalone generator with two flavors — email (with optional brand banner) and print (no banner). Long tables auto-paginate with a repeating header row.

Available MCP tools

| Group | Tools | |---|---| | Health | check_connection, now_nsk | | Lookups | list_organizations, list_products, search_counterparties, get_counterparty_by_inn | | Create | create_counterparty, create_counterparty_full, make_invoice_item, create_invoice | | Read | get_invoice, get_sale, list_invoices, list_sales, list_payments | | Control | post_document, unpost_document, mark_for_deletion | | Low-level | odata_get, odata_post, odata_patch |

Every tool carries its own docstring — see @mcp.tool() decorators in server.py.

Installation

git clone https://github.com/XRAT-dev/1c-fresh-mcp.git
cd 1c-fresh-mcp

# 1. Fill in .env
cp .env.example .env
$EDITOR .env           # set FRESH_BASE_URL, FRESH_PASSWORD, etc.

# 2. Install deps and verify connectivity
bash install.sh

Requirements

• Python ≥ 3.10 (uses PEP 604 X | None syntax)
• 1C:Fresh must have the OData interface enabled and a user with the "OData access" role (usually odata.user).

Environment variables

| Variable | Required | Purpose | |---|---|---| | FRESH_BASE_URL | ✅ | https://.1cfresh.com/a/ea/ (no trailing slash) | | FRESH_USERNAME | | Defaults to odata.user | | FRESH_PASSWORD | ✅ | OData user password | | FRESH_VERIFY_SSL | | True (default) | | FRESH_TIMEOUT | | Seconds, default 30 | | FRESH_TZ_OFFSET | | Hours from UTC (MSK = 3, Novosibirsk = 7) | | PDF_BANK_NAME | | Bank name for the PDF header | | PDF_BANK_BIK | | BIK code | | PDF_BANK_CORR_ACC | | Correspondent account | | PDF_BANK_SETTLEMENT_ACC | | Settlement account | | PDF_SIGNER_TITLE | | "Director" / "Entrepreneur" / etc. | | PDF_SIGNER_NAME | | Name printed on the signature line | | PDF_BANNER_PATH | | Path to a PNG banner (optional) |

Connect to an MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "1c-fresh": {
      "command": "python3",
      "args": ["/ABSOLUTE/PATH/TO/1c-fresh-mcp/server.py"],
      "env": {"PYTHONIOENCODING": "utf-8"}
    }
  }
}

Claude Code — same block under mcpServers in ~/.claude/settings.json.

See mcp-config.example.json for a copy-pasteable example.

Using the Python connector directly

from connector import Fresh1C
import config

config.assert_configured()
api = Fresh1C(config.BASE_URL, config.USERNAME, config.PASSWORD)

cp = api.get_counterparty_by_inn("1234567890")

item = Fresh1C.make_item(
    nom_guid="",
    qty=1, price=3903.70,
    description="Circuit breaker 63A 3P ABB",
)
inv = api.create_invoice(
    counterparty_guid=cp["Ref_Key"],
    items=[item],
    org_guid="",
)
api.post_document("СчетНаОплатуПокупателю", inv["Ref_Key"])

PDF invoice

Once PDF_BANK_* and PDF_SIGNER_* are set in .env:

python3 pdf_invoice.py 
# → Счёт_.pdf          (email variant)
#   Счёт__print.pdf    (print variant, no banner)

Known 1C:Fresh OData quirks handled here

| Limitation | Workaround | |---|---| | $filter on ИНН returns HTTP 500 | get_counterparty_by_inn filters client-side | | $expand=Товары returns HTTP 501 | get_invoice returns the full document; Товары is already inside | | POST to .../_Товары → 400 | create_invoice sends Товары inside the document body | | PATCH to .../_Товары → 405 | Update by replacing the whole document | | DELETE → 500 | Soft-delete via mark_for_deletion (PATCH DeletionMark=true) | | Dates come as /Date(…)/ | Parsed automatically by connector.parse_date() |

Contributing

Issues and PRs welcome. Keep .env.example in sync with any new env variables you add.

License

MIT — see [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: XRAT-dev
• Source: XRAT-dev/1c-fresh-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.