Metadata-Version: 2.4
Name: signnow-mcp-server
Version: 2.1.1
Summary: A Model Context Protocol (MCP) server that provides SignNow API integration capabilities.
License-File: LICENSE.md
Requires-Python: >=3.10
Requires-Dist: cryptography>=42
Requires-Dist: fastmcp<4,>=3.1.0
Requires-Dist: httpx[http2]>=0.25
Requires-Dist: mcp-ui-server>=1.0.0
Requires-Dist: mcp[cli]<2,>=1.10
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyjwt[crypto]>=2.8
Requires-Dist: starlette>=0.27
Requires-Dist: typer>=0.9
Requires-Dist: uvicorn[standard]>=0.24
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
Requires-Dist: langchain-mcp-adapters>=0.1.0; extra == 'langchain'
Requires-Dist: langchain-openai>=0.1.0; extra == 'langchain'
Requires-Dist: langchain>=0.1.0; extra == 'langchain'
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10.0; extra == 'llamaindex'
Requires-Dist: llama-index-llms-openai>=0.1.0; extra == 'llamaindex'
Requires-Dist: llama-index-tools-mcp>=0.1.0; extra == 'llamaindex'
Requires-Dist: python-dotenv>=1.0.0; extra == 'llamaindex'
Provides-Extra: smolagents
Requires-Dist: mcpadapt>=0.1.11; extra == 'smolagents'
Requires-Dist: smolagents>=1.20; extra == 'smolagents'
Provides-Extra: test
Requires-Dist: httpx>=0.25; extra == 'test'
Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
Requires-Dist: pytest-cov>=5.0; extra == 'test'
Requires-Dist: pytest-httpserver>=1.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Requires-Dist: respx>=0.22; extra == 'test'
Requires-Dist: smolagents[mcp]>=1.20; extra == 'test'
Description-Content-Type: text/markdown

<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. Supports `limit`/`offset` pagination (default: 50 items per page).
* **`list_contacts`** — Search CRM contacts by name, email, or phone. Returns id, email, first/last name, and company. Use before `send_invite` to resolve a recipient's email address by their name. Supports `per_page` (default 15, max 100).
* **`list_documents`** — Browse your documents, document groups and statuses. Supports `limit`/`offset` pagination (default: 50 items per page).
* **`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.
* **`upload_document`** — Upload a document from a local file path (`file_path`), public URL (`file_url`), or MCP resource attachment (`resource_uri`). For `file_path`, the resolved path must stay within the configured safe base directory (by default, the user's home directory); paths outside that base fail validation. Supported: PDF, DOC, DOCX, PNG, JPG, JPEG. Max 40 MB. Returns `document_id`, `filename`, `source`.
* **`send_invite_reminder`** — Send a signing reminder to pending signers on a document or document group.
* **`signnow_skills`** — Query the bundled SignNow skill library. Omit `skill_name` to list all available skills with descriptions; provide `skill_name` (e.g. `signnow101`) to fetch the full Markdown body. Use `signnow101` to learn SignNow entity types, invite types, and tool mappings.
  * List mode example: `{"skills": [{"name": "signnow101", "description": "SignNow 101 concepts reference... (description truncated for brevity)"}]}`
  * Fetch mode example: `{"name": "signnow101", "body": "# SignNow 101 — Concepts Reference\n..."}`

> Tip: Start with `signnow_skills` (no arguments) to discover available skills, then `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.

---
