unofficial type-safe Node.js SDK and MCP server for Parasut, the Turkish accounting platform. zero runtime dependencies in the SDK. 31 MCP tools for invoices, contacts, products, e-documents (GIB), inventory, and financials.

npm install @yigitkonur/parasut-node-sdk

or run the MCP server directly:

npx @yigitkonur/parasut-mcp-server

what it is

a pnpm monorepo with two packages:

• @yigitkonur/parasut-node-sdk — TypeScript SDK wrapping Parasut REST API v4. handles OAuth2, rate limiting, retries, JSON:API serialization. zero runtime deps, uses native fetch.
• @yigitkonur/parasut-mcp-server — MCP server exposing 31 tools over stdio. plug it into Claude Desktop, Cursor, or any MCP-compatible host and manage your entire Parasut account from natural language.

not affiliated with Parasut.

what the SDK covers

every resource gets list, get, create, update, delete, plus iterate (async generator), listAll, count, exists, and first for free.

| client.* | what it is | |:---|:---| | contacts | customers and suppliers | | salesInvoices | full CRUD + archive, cancel, recover, pay, list overdue/unpaid | | salesOffers | quotes and proposals | | purchaseBills | supplier invoices and expenses | | eArchives | e-arsiv documents with submitAndWait | | eInvoices | e-fatura with submitAndWait | | eInvoiceInboxes | GIB inbox lookup by tax number | | eSmms | e-serbest meslek makbuzu (freelancer receipts) | | accounts | bank and cash accounts | | products | goods and services | | employees | employee records | | salaries | salary payments | | taxes | tax payments (KDV, stopaj, SGK) | | bankFees | bank service charges | | inventoryLevels | stock counts per warehouse | | stockMovements | inbound/outbound inventory | | shipmentDocuments | delivery and waybill docs | | tags | labels for organizing | | itemCategories | product/expense categories | | transactions | financial ledger | | trackableJobs | polls async jobs until done/error |

what the MCP server exposes

31 tools across 8 domains:

| domain | tools | notes | |:---|:---|:---| | contacts | search_contacts, get_contact, create_contact, update_contact | filter by name, email, tax number, city | | invoices | search_invoices, get_invoice, create_invoice, cancel_invoice, recover_invoice, invoice_pdf, record_invoice_payment | all writes require confirm=true | | bills | search_bills, get_bill, create_bill, record_bill_payment | supplier invoices and expenses | | products | search_products, get_product, create_product, update_product | | | e-documents | check_einvoice_inbox, send_einvoice, send_earchive, send_esmm | double confirmation for GIB submissions | | financial | list_accounts, search_transactions, create_bank_fee, get_financial_summary | summary aggregates AR/AP/net across all accounts | | inventory | get_stock_levels, search_stock_movements | | | organization | list_categories, list_tags, list_employees, create_salary, create_tax | |

every write tool shows a preview first. pass confirm=true to execute. GIB e-document submissions additionally require i_understand_this_is_irreversible="YES".

SDK usage

import { ParasutClient } from '@yigitkonur/parasut-node-sdk';

const client = new ParasutClient({
  companyId: 115,
  credentials: {
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    username: '[email protected]',
    password: 'your-password',
  },
});

// list contacts
const contacts = await client.contacts.list({ filter: { name: 'acme' } });

// create an invoice
const invoice = await client.salesInvoices.create({
  contact_id: 123,
  item_type: 'invoice',
  description: 'consulting',
  details: [{ product_id: 456, quantity: 1 }],
});

// iterate all products (async generator, handles pagination)
for await (const product of client.products.iterate()) {
  console.log(product.attributes.name);
}

// submit e-invoice and wait for GIB response
const result = await client.eInvoices.submitAndWait(invoiceId, {
  scenario: 'basic',
  to: 'urn:mail:[email protected]',
});

MCP server setup

Claude Desktop

add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "parasut": {
      "command": "npx",
      "args": ["@yigitkonur/parasut-mcp-server"],
      "env": {
        "PARASUT_COMPANY_ID": "115",
        "PARASUT_CLIENT_ID": "...",
        "PARASUT_CLIENT_SECRET": "...",
        "PARASUT_USERNAME": "...",
        "PARASUT_PASSWORD": "..."
      }
    }
  }
}

standalone

PARASUT_COMPANY_ID=115 \
PARASUT_CLIENT_ID=your-client-id \
PARASUT_CLIENT_SECRET=your-client-secret \
[email protected] \
PARASUT_PASSWORD=yourpassword \
npx @yigitkonur/parasut-mcp-server

transport is stdio. logs go to stderr.

configuration

required env vars (MCP server)

| variable | description | |:---|:---| | PARASUT_COMPANY_ID | your Parasut company/firma ID | | PARASUT_CLIENT_ID | OAuth2 client ID | | PARASUT_CLIENT_SECRET | OAuth2 client secret | | PARASUT_USERNAME | login email | | PARASUT_PASSWORD | password |

optional

| variable | default | description | |:---|:---|:---| | PARASUT_BASE_URL | https://api.parasut.com/v4 | override API endpoint | | DEBUG | false | debug logging to stderr |

SDK config options

| option | default | description | |:---|:---|:---| | companyId | required | | | credentials or accessToken | required | OAuth2 creds or static token | | baseUrl | https://api.parasut.com/v4 | | | timeout | 30000 | request timeout in ms | | rateLimit.requestsPerWindow | 10 | token bucket limit | | rateLimit.windowMs | 10000 | token bucket window | | retry.maxRetries | 3 | | | retry.initialDelayMs | 100 | | | retry.maxDelayMs | 10000 | | | retry.backoffMultiplier | 2 | | | retry.retryableStatuses | [408, 429, 500, 502, 503, 504] | | | tokenStorage | in-memory | pluggable (implement TokenStorage interface) |

project structure

packages/parasut-node-sdk/
  src/
    index.ts                — public API barrel export
    client/
      ParasutClient.ts      — main client, lazy resource getters
      OAuth.ts              — password grant + refresh + auth code flow
      HttpTransport.ts      — native fetch wrapper with interceptors
      RateLimiter.ts        — token bucket (10 req / 10 sec)
      RetryHandler.ts       — exponential backoff with jitter
      QueryBuilder.ts       — JSON:API query param serialization
      JsonApi.ts            — JSON:API body builders and denormalizer
      errors.ts             — error hierarchy (auth, forbidden, not found, validation, rate limit)
    resources/
      BaseResource.ts       — abstract base with CRUD + iterate/listAll/count/exists/first
      contacts.ts           — customers and suppliers
      salesInvoices.ts      — invoices with archive/cancel/recover/pay
      eArchives.ts          — e-arsiv with submitAndWait
      eInvoices.ts          — e-fatura with submitAndWait
      eSmms.ts              — e-SMM with submitAndWait
      ...                   — 12 more resource files
    generated/
      types.ts              — auto-generated from swagger spec
      operations.ts         — operation metadata map

packages/parasut-mcp-server/
  src/
    index.ts                — entrypoint
    server.ts               — MCP server wiring (stdio transport)
    config.ts               — env var loading and validation
    client.ts               — singleton ParasutClient
    tools/
      contacts.ts           — 4 tools
      invoices.ts           — 7 tools
      bills.ts              — 4 tools
      products.ts           — 4 tools
      edocuments.ts         — 4 tools (double confirmation)
      financial.ts          — 4 tools
      inventory.ts          — 2 tools
      organization.ts       — 5 tools
    utils/
      response.ts           — formatters with next-step guidance
      errors.ts             — SDK error → structured MCP response mapping

development

pnpm install
pnpm build
pnpm test
pnpm lint

requires Node.js 18+ and pnpm 9.

types are generated from the Parasut Swagger spec:

pnpm --filter parasut-node-sdk generate-types

internals worth noting

• confirmation pattern — every write tool returns a preview by default. pass confirm=true to execute. GIB e-document tools require a second i_understand_this_is_irreversible="YES" field.
• async job polling — e-document submissions return a trackable job ID. submitAndWait() polls every 2 seconds up to 60 seconds until done or error.
• token refresh dedup — concurrent getValidToken() calls share a single in-flight refresh promise instead of hammering the token endpoint.
• page size cap — Parasut limits page size to 25. the SDK silently enforces Math.min(size, 25).
• LLM-optimized tool descriptions — every tool uses XML-structured descriptions with <usecase>, <instructions>, <example>, <returns> tags for better model comprehension.
• guided error responses — errors never throw in the MCP server. they're caught and returned as structured responses with recovery steps.

license

MIT