<details>
<summary><h1>About SignNow API</h1></summary>

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


</details>

---

# 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=<email>
SIGNNOW_PASSWORD=<password>
SIGNNOW_API_BASIC_TOKEN=<base64 basic token>
```

**2) OAuth 2.0 (for hosted/advanced scenarios)**

```
SIGNNOW_CLIENT_ID=<client_id>
SIGNNOW_CLIENT_SECRET=<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=<access_token>

# OAuth server (if you enable OAuth mode)
OAUTH_ISSUER=<your_issuer_url>
ACCESS_TTL=3600
REFRESH_TTL=2592000
ALLOWED_REDIRECTS=<comma,separated,uris>

# RSA keys for OAuth (critical in production)
OAUTH_RSA_PRIVATE_PEM=<PEM content>
OAUTH_JWK_KID=<key id>
```

### 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 (HTTP): use http://localhost:8000/mcp
```

You can list tools, call them with JSON args, and inspect responses.

---

## Tools

Each tool is described concisely; use an MCP client (e.g., Inspector) to view exact JSON schemas.

* **`list_all_templates`** — List templates & template groups with simplified metadata.
* **`list_documents`** — Browse your documents, document groups and statuses.
* **`create_from_template`** — Make a document or a group from a template/group.
* **`send_invite`** — Email invites (documents or groups), ordered recipients supported.
* **`create_embedded_invite`** — Embedded signing session without email delivery.
* **`create_embedded_sending`** — Embedded “sending/management” experience.
* **`create_embedded_editor`** — Embedded editor link to place/adjust fields.
* **`send_invite_from_template`** — One-shot: create from template and invite.
* **`create_embedded_sending_from_template`** — One-shot: template → embedded sending.
* **`create_embedded_editor_from_template`** — One-shot: template → embedded editor.
* **`create_embedded_invite_from_template`** — One-shot: template → embedded signing.
* **`get_invite_status`** — Current invite status/steps for document or group.
* **`get_document_download_link`** — Direct download link (merged output for groups).
* **`get_signing_link`** — Get signing link for a document or document group.
* **`get_document`** — Normalized document/group structure with field values.
* **`update_document_fields`** — Prefill text fields in individual documents.

> Tip: Start with `list_all_templates` → `create_from_template` → `create_embedded_*` / `send_invite`, then `get_invite_status` and `get_document_download_link`.

---

## FAQ / tips

* **STDIO vs Docker?** Prefer **STDIO** for local dev; inside Docker, use **HTTP**.
* **Sandbox vs production?** Start with SignNow’s sandbox/dev credentials; production requires proper OAuth and persistent RSA private key.
* **Where do I see exact tool schemas?** Use **MCP Inspector** or your client’s “tool details” view.
* **Where are examples?** See `examples/` in this repo for starter integrations.

---

## Examples

The `examples/` directory contains working examples of how to integrate the SignNow MCP Server with popular AI agent frameworks:

- **[LangChain](examples/langchain/langchain_example.py)** - Integration with LangChain agents using `langchain-mcp-adapters`
- **[LlamaIndex](examples/llamaindex/llamaindex_example.py)** - Integration with LlamaIndex agents using `llama-index-tools-mcp`
- **[SmolAgents](examples/smolagents/stdio_demo.py)** - Integration with SmolAgents framework using native MCP support

Each example demonstrates how to:
- Start the MCP server as a subprocess
- Convert MCP tools to framework-specific tool formats
- Create agents that can use SignNow functionality
- Handle environment variable configuration

To run an example:
```bash
# Make sure you have the required dependencies installed
pip install langchain-openai langchain-mcp-adapters  # for LangChain example
pip install llama-index-tools-mcp                   # for LlamaIndex example  
pip install smolagents                              # for SmolAgents example

# Set up your .env file with SignNow credentials and LLM configuration
# Then run the example
python examples/langchain/langchain_example.py
python examples/llamaindex/llamaindex_example.py
python examples/smolagents/stdio_demo.py
```

---

## Useful resources

### Sample apps

Explore ready-to-use sample apps to quickly test preparing, signing, and sending documents from your software using the SignNow API.

Try the [sample apps](https://docs.signnow.com/docs/signnow/sample-apps).

### API documentation
Find technical details on SignNow API requests, parameters, code examples, and possible errors. Learn more about the API functionality in detailed guides and use cases.

Read the [API documentation](https://docs.signnow.com/docs/signnow/welcome).

### SignNow API Helper MCP
Connect your AI to access API docs, generate code for complex signing workflows, and troubleshoot integration errors automatically.
[Access the API Helper MCP](https://github.com/signnow/sn-api-helper-mcp)

---

## License

MIT — see [LICENSE.md](./LICENSE.md).

---

**About**
SignNow MCP Server — maintained by the SignNow team. Issues and contributions welcome via GitHub pull requests.

---
