Bidsketch/signwell-mcp

Model Context Protocol server that orchestrates SignWell's e-signature workflows.
Prerequisites
- Node.js v18 or newer.
- A SignWell API key with document access (SIGNWELL_API_KEY environment variable).
- Optional overrides:
- SIGNWELL_API_BASE_URL for non-production endpoints.
- SIGNWELL_API_TIMEOUT_MS to tweak HTTP client timeouts (default 90000 ms; CLI flag --timeout on setup skips env prompts and writes this override).
Setup
Interactive Wizard (recommended)
1. Install dependencies if you have not already:
2. Bundle the CLI so MCP clients point at the build output:
3. Run the wizard and follow the prompts:
- Stores your SignWell secrets in ~/.config/signwell-mcp/env on Linux, ~/Library/Application Support/SignWell/MCP/env on macOS, or %APPDATA%/SignWell/MCP/env on Windows with 0700/0600 permissions.
- Automatically updates Claude Desktop, Claude Code, Cursor, and OpenCode configuration files (backups are captured before each write) so you do not have to hunt for platform paths.
- Client targets:
- Claude Code: ~/.claude.json at mcpServers.signwell
- Claude Desktop: claude_desktop_config.json at mcpServers.signwell
- Cursor: ~/.cursor/mcp.json at mcpServers.signwell
- OpenCode: ~/.config/opencode/opencode.json at mcp.signwell (Windows: %USERPROFILE%\.config\opencode\opencode.json)
- Uses each client's documented JSON wrapper and STDIO/local server shape so the server is visible after the client restarts.
- If a previous Claude Code install wrote the stale ~/.claude/mcp.json servers.signwell entry, rerunning setup backs up that legacy file and removes only the stale SignWell entry after writing the correct ~/.claude.json config.
- Use --print (or -p) to preview outputs without writing to disk, and --yes --api-key=... for non-interactive runs (CI, devcontainers, etc.).
- Pass --clients=claude-desktop,cursor to limit which MCP clients the wizard configures; omit for "all". Use --timeout= only if you need a non-default HTTP timeout.
- After bundling (npm run build) and publishing the package, end users can invoke the same wizard with npx @signwell/mcp setup. Installing globally also enables invoking signwell-mcp setup directly.
Manual exports
Prefer to manage env vars yourself? Export the required values before running the server:
Installation (npm)
Once the package is published to npm (GitHub: Bidsketch/signwell-mcp):
- Run the setup wizard without installing anything globally:
- Install globally if you prefer a persistent binary:
After configuration, start the MCP server via signwell-mcp (requires Node.js v18+).
The signwell-mcp.mcpb file is a separate Claude Desktop extension artifact. It uses the root manifest.json and should be rebuilt for releases after running npm run build.
Local Development Workflow
1. Install dependencies: npm install
2. Bundle the CLI entrypoint (required for MCP client configs): npm run build
3. Configure credentials: node build/index.js setup (or npx @signwell/mcp setup once published)
4. Start the MCP server locally: npm start (runs node build/index.js)
5. Open another terminal to run tests and linters before committing:
6. When using MCP inspector or other clients, point them at npm start (stdio).
Running the Server
- Development entrypoint (stdio transport):
- CLI helpers:
- node build/index.js --help prints usage and env expectations.
- node build/index.js --version prints the current build.
- node build/index.js setup launches the setup wizard described above when working from source.
- Once the package is bundled/published, npx @signwell/mcp setup runs the wizard and SIGNWELL_API_KEY=... npx @signwell/mcp starts the server via the packaged binary (global installs can call signwell-mcp ... directly).