@sparkdesk/mcp-server

MCP server for SparkDesk — full CRUD and search across CRM, Work, Expenses, and read-only Analytics, exposed as tools for Claude, ChatGPT, and any MCP client.

It runs in two ways from the same package:

• Local (stdio): npx @sparkdesk/mcp-server with a SPARKDESK_API_KEY env var.
• Remote (Streamable HTTP): the hosted mcp Supabase Edge Function imports this package and serves it at a URL, so no local process is required.

Both talk to the org-scoped public-api gateway; every operation is scoped to the org that owns the API key.

Getting an API key

An org Owner/Admin mints a key in SparkDesk (Settings → API Keys), which calls the api-keys Edge Function. Keys look like sk_live_... and are shown once. Scope: all tool calls made with a key act on that key's organization.

Connecting

Remote URL (recommended — works on any device)

https://tzxhxezupualwekwhuct.supabase.co/functions/v1/mcp?api_key=sk_live_YOUR_KEY

• Claude.ai → Settings → Integrations → Add custom integration: paste the URL above.
• ChatGPT → Settings → Connectors → Add: paste the URL above.
• Claude Desktop (claude_desktop_config.json):

  {
    "mcpServers": {
      "sparkdesk": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "https://tzxhxezupualwekwhuct.supabase.co/functions/v1/mcp?api_key=sk_live_YOUR_KEY"]
      }
    }
  }

The key may also be sent as an X-API-Key header or Authorization: Bearer for clients that support custom headers.

Local stdio (Claude Desktop)

{
  "mcpServers": {
    "sparkdesk": {
      "command": "npx",
      "args": ["-y", "@sparkdesk/mcp-server"],
      "env": { "SPARKDESK_API_KEY": "sk_live_YOUR_KEY" }
    }
  }
}

Optional env: SPARKDESK_API_URL to point at a non-default gateway (e.g. a local supabase functions serve instance).

Tools

Naming is entity_action. Standard CRUD entities expose _search, _get, _create, _update, _delete (search takes query, page, limit plus entity filters).

• CRM: account_*, contact_*, lead_*, opportunity_*, case_*, note_*, activity_list, customfield_list_defs / customfield_get_values / customfield_set_value
• Work: project_*, task_*, timeentry_*
• Finance/Expenses: expense_*, expensecategory_list, expensereport_*, invoice_*, contract_*, budget_*, timesheet_*
• Analytics (read-only): analytics_lead_pipeline, analytics_revenue_by_account, analytics_time_by_project, analytics_expense_by_category (optional from/to)
• Utility: search_global, lookup, context_whoami
• Reports: report_list, report_get

Development

npm install
npm run build      # tsc -> dist/
npm run typecheck
npm run dev        # tsx src/index.ts (stdio)

Inspect tools with the MCP Inspector:

# stdio
SPARKDESK_API_KEY=sk_live_... npx @modelcontextprotocol/inspector node dist/index.js
# remote
npx @modelcontextprotocol/inspector   # then connect to the /functions/v1/mcp?api_key=... URL

Versioning

0.3.x added entity_action naming, _get tools, notes, custom fields, analytics, global search, context_whoami, and the remote Streamable HTTP transport. Tool names changed from the 0.2.x action_entity form (e.g. create_contact → contact_create).