---
title: "Local setup"
url: "https://docs.signnow.com/docs/mcp-local-setup"
type: "page"
section: "Documentation"
slug: "mcp-local-setup"
---

# Local setup

# Local setup

Run the SignNow MCP server locally with your personal credentials and connect it to your preferred MCP-compatible client.

---

## Prerequisites

- **Python 3.11+** installed (verify with `python3 --version`).
- **uvx** installed (verify with `uvx --version`). If missing, install `uv`:

   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

- A SignNow [developer account](https://snseats.signnow.com/purchase/business_free_trial/loggedout?type=api) with an active API application. Your first application is created automatically.
- Credentials for one of the two supported authentication methods shown below.

<!--
type: tab
title: API key
-->

- `SIGNNOW_API_KEY` — the **API key** from your SignNow API application.

> To copy the **API key**, go to your developer account API dashboard → **Apps and Keys** → select your application → **API Keys** → copy the API key.

<!--
type: tab
title: Email and password
-->

- `SIGNNOW_USER_EMAIL` — your account email.
- `SIGNNOW_PASSWORD` — your account password.
- `SIGNNOW_API_BASIC_TOKEN` — the **Basic Authorization Token** from your SignNow API application.

> To copy the **Basic Authorization Token**, go to your developer account API dashboard → **Apps and Keys** → select your application → **OAuth 2.0** tab → copy the **Basic Authorization Token**.

<!-- type: tab-end -->

---

## Verify the server starts

Run the server once from the terminal to confirm `uvx` can fetch and launch the package. The server reads credentials from environment variables at startup, so pass them inline (replace the placeholder values with your real credentials).

<!--
type: tab
title: API key
-->

```bash
SIGNNOW_API_KEY="your-api-key" \
uvx --from signnow-mcp-server sn-mcp serve
```

<!--
type: tab
title: Email and password
-->

```bash
SIGNNOW_USER_EMAIL="your.email@example.com" \
SIGNNOW_PASSWORD="your-password" \
SIGNNOW_API_BASIC_TOKEN="your-basic-token" \
uvx --from signnow-mcp-server sn-mcp serve
```

<!-- type: tab-end -->

This starts a STDIO server. If the process launches without errors and waits for a client, it is working. Stop it with `Ctrl+C`. The first run is slower because `uvx` downloads the package from PyPI.

> If you run `uvx --from signnow-mcp-server sn-mcp serve` without the environment variables, the server exits with a Pydantic `ValidationError` for `SignNowConfig`. That's the package telling you the credentials are missing.

---

## Connect Claude Desktop

### Step 1. Configure Claude Desktop

Locate the Claude Desktop config file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Or open it from the app: **Claude Desktop** → **Settings** → **Developer** → **Edit Config**.

![mcp_claude_edit_config.png](/reference-assets/images/MCP/mcp_claude_edit_config.png)

Add the following entry under `mcpServers`. Replace the placeholder values with your real credentials.

<!--
type: tab
title: API key
-->

```json
{
  "mcpServers": {
    "signnow-local": {
      "command": "uvx",
      "args": ["--from", "signnow-mcp-server", "sn-mcp", "serve"],
      "env": {
        "SIGNNOW_API_KEY": "your-api-key"
      }
    }
  }
}
```

<!--
type: tab
title: Email and password
-->

```json
{
  "mcpServers": {
    "signnow-local": {
      "command": "uvx",
      "args": ["--from", "signnow-mcp-server", "sn-mcp", "serve"],
      "env": {
        "SIGNNOW_USER_EMAIL": "your.email@example.com",
        "SIGNNOW_PASSWORD": "your-password",
        "SIGNNOW_API_BASIC_TOKEN": "your-basic-token"
      }
    }
  }
}
```

<!-- type: tab-end -->

The `${env:VARIABLE_NAME}` placeholder syntax also works for any of these variables, but only if they are exported in the system environment that Claude Desktop sees. For a quick local setup, paste the values directly.

### Step 2. Disable the cloud SignNow connector

If you have the official hosted SignNow connector enabled in Claude Desktop, turn it off. Otherwise both connectors expose the same tool names and the model gets confused about which one to call.

### Step 3. Restart and verify

- Quit Claude Desktop completely (on macOS use `Cmd+Q`, do not just close the window), then reopen it.
- In a new chat, ask: `list available signnow tools`. You should see entries such as `list_all_templates`, `list_documents`, `send_invite`, `create_embedded_invite`, and others.
- Smoke test: `list my SignNow templates` or `upload this file to SignNow: https://pdfobject.com/pdf/sample.pdf`.

### Troubleshooting

| Problem | Solution |
|---|---|
| Server does not start from the terminal | Confirm `uvx` is on `PATH` (run `which uvx`) and Python 3.11+ is installed. |
| Claude does not see the tools | Check the MCP logs at `~/Library/Logs/Claude/mcp*.log` (macOS). The error is usually wrong credentials or a stale `uvx` cache. |
| 401 or 403 errors on tool calls | The credentials are wrong. If using the API key, confirm it was copied from **Apps and Keys** → **API Keys**. If using email and password, confirm the **Basic Authorization Token** is from **Apps and Keys** → **OAuth 2.0** (not the API key or an access token). |
| Need to force a fresh package version | Run `uvx --refresh --from signnow-mcp-server sn-mcp serve`. |

---

## Connect VS Code (GitHub Copilot)

### Step 1. Configure the server

Create a file `.vscode/mcp.json` in your workspace. Add the following configuration to this file, replacing the placeholders with your actual credentials.

<!--
type: tab
title: API key
-->

```json
{
  "servers": {
    "signnow": {
      "command": "uvx",
      "args": [
        "--from",
        "signnow-mcp-server",
        "sn-mcp",
        "serve"
      ],
      "env": {
        "SIGNNOW_API_KEY": "your_api_key"
      }
    }
  }
}
```

<!--
type: tab
title: Email and password
-->

```json
{
  "servers": {
    "signnow": {
      "command": "uvx",
      "args": [
        "--from",
        "signnow-mcp-server",
        "sn-mcp",
        "serve"
      ],
      "env": {
        "SIGNNOW_USER_EMAIL": "your_account_email",
        "SIGNNOW_PASSWORD": "your_account_password",
        "SIGNNOW_API_BASIC_TOKEN": "your_basic_authorization_token"
      }
    }
  }
}
```

<!-- type: tab-end -->

### Step 2. Restart VS Code

Restart VS Code to load the new configuration.

### Step 3. Open GitHub Copilot Chat

Click the chat icon in the sidebar or press `Ctrl+Cmd+I` (macOS) / `Ctrl+Alt+I` (Windows).

### Step 4. Enable Agent Mode

Look for the toggle or mode selector in the chat window and switch to **Agent Mode** (sometimes labeled as **Workspace** or **Attach Context**).

![mcp_vs_agent_mode.png](/reference-assets/images/MCP/mcp_vs_agent_mode.png)

### Step 5. Verify tools

Ensure the SignNow MCP server tools are visible in the context menu (paperclip icon) or that the agent confirms it can access them.

![mcp_vs_tools.png](/reference-assets/images/MCP/mcp_vs_tools.png)

### Step 6. Test the connection

Enter a command like `List my documents` to verify the MCP server is working correctly.

> The same configuration applies in Cursor. Create the configuration file `.cursor/mcp.json` in your workspace and reuse the JSON block above.

---

## See also

- [Overview](/docs/mcp-server)
- [Quick start](/docs/mcp-quick-start)
- [Hosted setup](/docs/mcp-hosted-setup)
- [SignNow MCP Server tools](/docs/mcp-tools)


---
*Full page: https://docs.signnow.com/docs/mcp-local-setup*