Skip to main content
Glama
bowimi-mcp

bowimi-mcp

by Caezarr

bowimi-mcp

CI License: MIT

An MCP server that lets Claude (or any MCP host) query and update the Bowimi field-sales CRM in plain language: routes, locations, contacts, orders, products, tasks, surveys and team reports, exposed as 85 tools.

The problem

Field-sales teams keep their route plans, points of sale, orders and visit history in a CRM built for forms and dashboards, not questions. A rep who wants "which stops on my route haven't been visited in 90 days, and what did they last order?" has to click through several screens, and a manager who wants a weekly recap per rep exports to a spreadsheet. Generic AI assistants cannot help because they have no access to that data. Bowimi has an API, but it uses non-standard HTTP verbs (QUERY, LIST) and a response envelope that a model cannot call reliably on its own.

Related MCP server: empresa-mcp-demo

How it solves it

bowimi-mcp is a thin, stateless stdio adapter between an MCP host and the Bowimi API. Each tool call maps to one or a few Bowimi requests and returns JSON to the model.

  • One tool per CRM action, typed. Every tool has a description written for the model and a zod input schema, so bad arguments are rejected before any HTTP call.

  • Composite tools for real questions. Besides 1:1 endpoint tools, some combine calls into answers reps and managers ask for: get_weekly_report, get_team_overview, get_route_stops_with_tasks, get_location_full_profile. One failing rep does not fail a team report.

  • The API's quirks live in one client. BowimiClient wraps the QUERY and LIST verbs and unwraps the { Data } envelope; errors become Bowimi API <path> → <status>: <ErrorType>: <Message> so the model sees what went wrong, never a stack trace.

  • Testable without an account. createServer() takes the client as a parameter, so the test suite drives the real MCP server against a mocked client with the network disabled.

  • API key first. A static Bearer key is preferred; email and password session login is supported for accounts without one.

MCP host (Claude Desktop, ...) --stdio/JSON-RPC--> index.js -> server.js -> tools/*.js -> BowimiClient --HTTPS--> {subdomain}.bowimi.com/_api/v4.6.1

Module map, error handling and how to add a tool: docs/ARCHITECTURE.md.

Try it

Requires Node.js 18+.

Offline, no Bowimi account (about 2 minutes)

git clone https://github.com/Caezarr/bowimi-mcp && cd bowimi-mcp
npm ci
npm test

Expected output (excerpt):

# tests 21
# pass 21
# fail 0

List the tools the server exposes with the official MCP Inspector CLI. Dummy credentials are enough: the server only contacts Bowimi when a tool is called.

npx -y @modelcontextprotocol/inspector@0.17.2 --cli node src/index.js \
  -e BOWIMI_SUBDOMAIN=demo -e BOWIMI_API_KEY=demo:offline \
  --method tools/list 2>/dev/null \
  | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const t=JSON.parse(s).tools;console.log(t.length+" tools");console.log(t.slice(0,4).map(x=>x.name).join("\n")+"\n...")})'
85 tools
get_app_info
list_users
get_current_user
invite_user
...

Drop the final pipe to see every tool's description and JSON input schema. Without credentials the server refuses to start:

node src/index.js
# Required: BOWIMI_SUBDOMAIN + (BOWIMI_API_KEY or BOWIMI_EMAIL+BOWIMI_PASSWORD)   (exit 1)

With a real Bowimi account

  1. In Bowimi, get an API key: Settings → Integrations → Zapier → API Key. Its format is subdomain:longkey.

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

{
  "mcpServers": {
    "bowimi": {
      "command": "node",
      "args": ["/absolute/path/to/bowimi-mcp/src/index.js"],
      "env": {
        "BOWIMI_SUBDOMAIN": "yoursubdomain",
        "BOWIMI_API_KEY": "yoursubdomain:yourapikey"
      }
    }
  }
}
  1. Restart Claude Desktop and ask, for example:

Prompt

Tools the model typically uses

"Show me my route for today"

get_route, get_route_summary

"Which stops haven't been visited since July?"

get_route with notVisitedSince

"Task and order counts this week"

get_task_summary, get_order_summary

"Weekly team performance"

get_weekly_report, get_team_overview

Email and password (BOWIMI_EMAIL, BOWIMI_PASSWORD) also work in place of the API key; the server then holds a session cookie in memory, so use it only on a machine you control. See SECURITY.md.

How it works

  1. src/index.js reads the BOWIMI_* variables, builds the auth and client, and serves over stdio. It is the only module with side effects.

  2. src/server.js creates the McpServer and calls each domain module's register*Tools: account, tags, attributes, locations, companies, tasks, orders, products, surveys, route, analytics, debug.

  3. Each tool validates its input with zod, calls BowimiClient, and returns pretty-printed JSON via jsonResult().

  4. BowimiClient (src/client.js) has one method per endpoint and handles QUERY and LIST alongside GET/POST/PATCH/DELETE.

  5. Non-2xx responses become a BowimiApiError; the MCP SDK turns it into a tool result with isError: true.

Details: docs/ARCHITECTURE.md. Full tool reference with schemas: docs/TOOLS.md and docs/TOOL-CATALOG.md.

Proof

  • npm test: 21 node:test cases, no network. test/server.test.js builds the real server around a mocked client and checks that exactly the expected 85 tools are registered, each with a description and object schema; that arguments are validated before reaching the client; and that API errors come back as isError results carrying Bowimi's message. Other suites cover the QUERY and LIST request contracts with a mocked fetch, error-envelope parsing and success-body unwrapping.

  • npm run typecheck: tsc --checkJs over the JSDoc types.

  • CI runs a syntax check, the type check and the tests on every pull request.

Limits and status

  • Nothing in this repository proves behaviour against the live Bowimi API: tests use mocks, and the commands above were verified offline only. Use a test account first.

  • 34 of the 85 tools write (create, update, delete, invite, set, add, remove), and debug_api sends a raw request to any Bowimi endpoint. There is no read-only mode; the API key's own permissions are the only limit, and the MCP host's tool approval is your safeguard.

  • Bowimi's location/map and activity endpoints returned server errors when last tested, which affects get_activity (issue #1, open). Prefer get_route, get_location, get_visit_summary and get_insights.

  • Role management needs admin permissions and is not available with field-sales API keys.

  • On startup the server makes one request to raw.githubusercontent.com to check for a newer version; it fails silently offline.

  • Not published to npm: run from a clone.

Development

npm ci
npm test            # node:test, no network
npm run typecheck   # tsc over JSDoc types
npm run check       # both
npm run dev         # node --watch src/index.js (needs BOWIMI_* env)

To add a tool, follow the four steps in docs/ARCHITECTURE.md#adding-a-tool.

See CONTRIBUTING.md, SUPPORT.md, SECURITY.md and CODE_OF_CONDUCT.md.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Demonstration MCP server for Claude Team integration, enabling querying of sample business data (orders, clients, products) and real-time currency exchange rates through natural language.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      MCP server that integrates with Microsoft Dynamics 365 Business Central, enabling querying of customers, items, and sales orders through natural language commands in Claude Desktop.
      10
      -