About SignNow API
The SignNow REST API empowers users to deliver a seamless eSignature experience for signers, preparers, and senders. Pre-fill documents, create embedded branded workflows for multiple signers, request payments, and track signature status in real-time. Ensure signing is simple, secure, and intuitive on any device.
**What you can do with the SignNow API**:
* Send documents and document groups for signature in a role-based order
* Create reusable templates from documents
* Pre-fill document fields with data
* Collect payments as part of the signing flow
* Embed the document sending, signing, or editing experience into your website, application, or any system of record
* Track signing progress and download the completed documents
---
# SignNow MCP Server
> A Model Context Protocol (MCP) server that gives AI agents secure, structured access to **SignNow** eSignature workflows — templates, embedded signing, invites, status tracking, and document downloads — over **STDIO** or **Streamable HTTP**.
> mcp-name: io.github.signnow/sn-mcp-server
---
## Table of contents
* [Features](#features)
* [Quick start](#quick-start)
* [Prerequisites](#prerequisites)
* [Quick run (uvx)](#quick-run-uvx)
* [1. Setup Environment Variables](#1-setup-environment-variables)
* [2. Install and Run](#2-install-and-run)
* [Local/Remote (HTTP)](#localremote-http)
* [Docker](#docker)
* [Docker Compose](#docker-compose)
* [Configuration](#configuration)
* [Authentication options](#authentication-options)
* [SignNow & OAuth settings](#signnow--oauth-settings)
* [Production key management](#production-key-management)
* [Client setup](#client-setup)
* [VS Code — GitHub Copilot (Agent Mode) / Cursor](#vs-code--github-copilot-agent-mode--cursor)
* [Claude Desktop](#claude-desktop)
* [Glama (hosted MCP)](#glama-hosted-mcp)
* [MCP Inspector (testing)](#mcp-inspector-testing)
* [Tools](#tools)
* [FAQ / tips](#faq--tips)
* [Examples](#examples)
* [Useful resources](#useful-resources)
* [Sample apps](#sample-apps)
* [API documentation](#api-documentation)
* [SignNow API Helper MCP](#signnow-api-helper-mcp)
* [License](#license)
---
## Features
* **Templates & groups**
* Browse all templates and template groups
* Create documents or groups from templates (one-shot flows included)
* **Invites & embedded UX**
* Email invites and ordered recipients
* **Embedded signing/sending/editor** links for in-app experiences
* **Status & retrieval**
* Check invite status and step details
* Download final documents (single or merged)
* Read normalized document/group structure for programmatic decisions
* **Transports**
* **STDIO** (best for local clients)
* **Streamable HTTP** (best for Docker/remote)
---
## Quick start
### Prerequisites
- SignNow account. Create a [free developer account](https://www.signnow.com/developers).
- SignNow Credentials: You will need your account email, password, and the application Basic Authorization Token. [Getting started](https://docs.signnow.com/docs/signnow/get-started).
- An active SignNow API application.
- Python 3.11+ installed on your system (check with python3 --version)
- UVX installed (check with uvx --version). Recommended for the quickest setup.
- Environment variables configured
- If your client supports Streamable HTTP, you can use the pre-deployed server URL `https://mcp-server.signnow.com/mcp` instead of running it locally.
### Quick run (uvx)
If you use `uv`, you can run the server without installing the package:
```bash
uvx --from signnow-mcp-server sn-mcp serve
```
### 1. Setup Environment Variables
```bash
# Create .env file with your SignNow credentials
# You can copy from env.example if you have the source code
# Or create .env file manually with required variables (see Environment Variables section below)
```
### 2. Install and Run
#### Option A: Install from PyPI (Recommended)
```bash
# Install the package from PyPI
pip install signnow-mcp-server
# Run MCP server in standalone mode
sn-mcp serve
```
#### Option B: Install from Source (Development)
```bash
# 1) Clone & configure
git clone https://github.com/signnow/sn-mcp-server.git
cd sn-mcp-server
cp .env.example .env
# fill in your values in .env
# 2) Install (editable for dev)
pip install -e .
# 3) Run as STDIO MCP server (recommended for local tools & Inspector)
sn-mcp serve
```
> STDIO is ideal for desktop clients and local testing.
### Local/Remote (HTTP)
```bash
# Start HTTP server on 127.0.0.1:8000
sn-mcp http
# Custom host/port
sn-mcp http --host 0.0.0.0 --port 8000
# Dev reload
sn-mcp http --reload
```
By default, the **Streamable HTTP** MCP endpoint is served under `/mcp`. Example URL:
```
http://localhost:8000/mcp
```
### Docker
```bash
# Build
docker build -t sn-mcp-server .
# Run HTTP mode (recommended for containers)
docker run --env-file .env -p 8000:8000 sn-mcp-server sn-mcp http --host 0.0.0.0 --port 8000
```
> STDIO inside containers is unreliable with many clients. Prefer HTTP when using Docker.
### Docker Compose
```bash
# Only the MCP server
docker-compose up sn-mcp-server
# Both services (if defined)
docker-compose up
```
---
## Configuration
Copy `.env.example` → `.env` and fill in values. All settings are validated via **pydantic-settings** at startup.
### Authentication options
**1) Username / Password (recommended for desktop dev flows)**
```
SIGNNOW_USER_EMAIL=
SIGNNOW_PASSWORD=
SIGNNOW_API_BASIC_TOKEN=
```
**2) OAuth 2.0 (for hosted/advanced scenarios)**
```
SIGNNOW_CLIENT_ID=
SIGNNOW_CLIENT_SECRET=
# + OAuth server & RSA settings below
```
> When running via some desktop clients, only user/password may be supported.
### SignNow & OAuth settings
```
# SignNow endpoints (defaults shown)
SIGNNOW_APP_BASE=https://app.signnow.com
SIGNNOW_API_BASE=https://api.signnow.com
# Optional direct API token (not required for normal use)
SIGNNOW_TOKEN=
# OAuth server (if you enable OAuth mode)
OAUTH_ISSUER=
ACCESS_TTL=3600
REFRESH_TTL=2592000
ALLOWED_REDIRECTS=
# RSA keys for OAuth (critical in production)
OAUTH_RSA_PRIVATE_PEM=
OAUTH_JWK_KID=
```
### Production key management
If `OAUTH_RSA_PRIVATE_PEM` is missing in production, a new RSA key will be generated on each restart, **invalidating all existing tokens**. Always provide a persistent private key via secrets management in prod.
---
## Client setup
### VS Code — GitHub Copilot (Agent Mode) / Cursor
Create `.vscode/mcp.json` / `.cursor/mcp.json` in your workspace:
**STDIO (local):**
```json
{
"servers": {
"signnow": {
"command": "sn-mcp",
"args": ["serve"],
"env": {
"SIGNNOW_USER_EMAIL": "${env:SIGNNOW_USER_EMAIL}",
"SIGNNOW_PASSWORD": "${env:SIGNNOW_PASSWORD}",
"SIGNNOW_API_BASIC_TOKEN": "${env:SIGNNOW_API_BASIC_TOKEN}"
}
}
}
}
```
**STDIO (uvx — no local install):**
```json
{
"servers": {
"signnow": {
"command": "uvx",
"args": ["--from", "signnow-mcp-server", "sn-mcp", "serve"],
"env": {
"SIGNNOW_USER_EMAIL": "${env:SIGNNOW_USER_EMAIL}",
"SIGNNOW_PASSWORD": "${env:SIGNNOW_PASSWORD}",
"SIGNNOW_API_BASIC_TOKEN": "${env:SIGNNOW_API_BASIC_TOKEN}"
}
}
}
}
```
**HTTP (remote or Docker):**
```json
{
"servers": {
"signnow": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}
```
Then open Chat → **Agent mode**, enable the **signnow** tools, and use them in prompts.
Note: The same configuration applies in Cursor — add it under MCP settings (STDIO or HTTP). For STDIO, you can also use `uvx` as shown above.
### Claude Desktop
Use Desktop Extensions or the manual MCP config (Developer → Edit config).
Steps:
1. Open Claude Desktop → Developer → Edit config
2. Add a new server entry under `mcpServers`
3. Save and restart Claude Desktop
Examples:
**STDIO (local install):**
```json
{
"mcpServers": {
"signnow": {
"command": "sn-mcp",
"args": ["serve"],
"env": {
"SIGNNOW_USER_EMAIL": "${env:SIGNNOW_USER_EMAIL}",
"SIGNNOW_PASSWORD": "${env:SIGNNOW_PASSWORD}",
"SIGNNOW_API_BASIC_TOKEN": "${env:SIGNNOW_API_BASIC_TOKEN}"
}
}
}
}
```
**STDIO (uvx — no local install):**
```json
{
"mcpServers": {
"signnow": {
"command": "uvx",
"args": ["--from", "signnow-mcp-server", "sn-mcp", "serve"],
"env": {
"SIGNNOW_USER_EMAIL": "${env:SIGNNOW_USER_EMAIL}",
"SIGNNOW_PASSWORD": "${env:SIGNNOW_PASSWORD}",
"SIGNNOW_API_BASIC_TOKEN": "${env:SIGNNOW_API_BASIC_TOKEN}"
}
}
}
}
```
**HTTP (remote or Docker):**
```json
{
"mcpServers": {
"signnow": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}
```
Then enable the server in Claude’s chat and start using the tools.
### Glama (hosted MCP)
Deploy and run this server on Glama with minimal setup:
Steps:
1. Open the server page on Glama: [sn-mcp-server on Glama](https://glama.ai/mcp/servers/@mihasicehcek/sn-mcp-server)
2. Click the red "Deploy Server" button
3. In environment variables, provide:
- `SIGNNOW_USER_EMAIL`
- `SIGNNOW_PASSWORD`
- `SIGNNOW_API_BASIC_TOKEN`
- (other variables can be left as defaults)
4. Create an access token in Glama and copy the endpoint URL. It will look like:
```
https://glama.ai/endpoints/{someId}/mcp?token={glama-mcp-token}
```
Use this HTTP MCP URL in any client that supports HTTP transport (e.g., VS Code/Cursor JSON config or Claude Desktop HTTP example above).
### MCP Inspector (testing)
Great for exploring tools & schemas visually.
```bash
# Start Inspector (opens UI on localhost)
npx @modelcontextprotocol/inspector
# Connect (STDIO): run your server locally and attach
sn-mcp serve
# Or connect
---
