Famulor-MCP

<p align="center">
  <img src="https://app.famulor.io/famulor-mcp-logo.svg" alt="Famulor" width="80" height="80" />
</p>

<h1 align="center">Famulor MCP</h1>

<p align="center">
  Connect Claude, Codex, Cursor, VS Code, and other MCP clients to the complete
  tenant-safe Famulor platform API.
</p>

<p align="center">
  <a href="https://app.famulor.io/mcp">MCP endpoint</a> ·
  <a href="https://app.famulor.io/settings?panel=apikeys">API &amp; MCP settings</a> ·
  <a href="https://docs.famulor.io">Docs</a>
</p>

<p align="center">
  <a href="https://github.com/bekservice/Famulor-MCP">
    <img src="https://img.shields.io/badge/GitHub-bekservice%2FFamulor--MCP-181717?logo=github" alt="GitHub" />
  </a>
  <a href="https://www.famulor.io">
    <img src="https://img.shields.io/badge/Famulor-voice%20agents-29C5F6" alt="Famulor" />
  </a>
  <a href="https://modelcontextprotocol.io">
    <img src="https://img.shields.io/badge/protocol-MCP-blueviolet" alt="MCP" />
  </a>
  <a href="https://vercel.com">
    <img src="https://img.shields.io/badge/hosted%20on-Vercel-000000?logo=vercel" alt="Vercel" />
  </a>
  <a href="LICENSE">
    <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT" />
  </a>
</p>

<p align="center">
  <img src="https://www.famulor.io/_next/image?url=https%3A%2F%2Fanzpxaqhcbkfyqdk.public.blob.vercel-storage.com%2Fblog-images%2F1766256900040-79z4hr1mztw.webp&w=3840&q=75" alt="Famulor AI voice agents" width="100%" />
</p>

---

## Setup

Add the server in your client, then sign in to Famulor and approve the requested
workspace permissions in the browser. Claude and ChatGPT use OAuth; there is no
API key to paste into their connector settings.

> **Server URL**: `https://app.famulor.io/mcp` is the canonical endpoint.
> `https://mcp.famulor.io/mcp` remains online only for legacy clients.

<details open>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add --transport http famulor https://app.famulor.io/mcp
```

Add the server first, then complete the browser-based OAuth flow.
</details>

<details>
<summary><b>Claude Desktop</b></summary>

**Settings > Connectors > Add custom connector**

```
https://app.famulor.io/mcp
```

Copy the URL, paste it into the connector dialog, and sign in when prompted.
</details>

<details>
<summary><b>Cursor</b></summary>

`.cursor/mcp.json`

```json
{
  "mcpServers": {
    "famulor": {
      "type": "http",
      "url": "https://app.famulor.io/mcp"
    }
  }
}
```

Add the server first, then complete the browser-based OAuth flow.
</details>

<details>
<summary><b>Windsurf</b></summary>

`~/.codeium/windsurf/mcp_config.json`

```json
{
  "mcpServers": {
    "famulor": {
      "serverUrl": "https://app.famulor.io/mcp"
    }
  }
}
```

Add the server first, then complete the browser-based OAuth flow.
</details>

<details>
<summary><b>VS Code</b></summary>

`.vscode/mcp.json`

```json
{
  "servers": {
    "famulor": {
      "type": "http",
      "url": "https://app.famulor.io/mcp"
    }
  }
}
```

Add the server first, then complete the browser-based OAuth flow.
</details>

<details>
<summary><b>Cline</b></summary>

**Cline extension > MCP Servers > Configure**

```json
{
  "mcpServers": {
    "famulor": {
      "url": "https://app.famulor.io/mcp"
    }
  }
}
```

Add the server first, then complete the browser-based OAuth flow.
</details>

<details>
<summary><b>Continue</b></summary>

`~/.continue/config.yaml`

```yaml
mcpServers:
  - name: famulor
    type: streamable-http
    url: "https://app.famulor.io/mcp"
```

Add the server first, then complete the browser-based OAuth flow.
</details>

<details>
<summary><b>OpenClaw</b></summary>

```bash
openclaw mcp add famulor --url https://app.famulor.io/mcp --transport streamable-http --auth oauth
openclaw mcp login famulor
```

Or in `~/.openclaw/openclaw.json`:

```json
{
  "mcp": {
    "servers": {
      "famulor": {
        "url": "https://app.famulor.io/mcp",
        "transport": "streamable-http",
        "auth": "oauth"
      }
    }
  }
}
```

Tip: there is also a ready-made Famulor skill — `openclaw skills install famulor-skill`.
</details>

<details>
<summary><b>Hermes Agent</b></summary>

```bash
hermes mcp add famulor --url https://app.famulor.io/mcp
hermes mcp login famulor
```

Or in `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  famulor:
    url: "https://app.famulor.io/mcp"
    auth: oauth
```

Apply in-session with `/reload-mcp`.
</details>

<details>
<summary><b>Legacy npx/stdio package</b></summary>

The earlier npm package is retained for compatibility, but it does not expose
the current platform's complete tool catalog. New integrations should use the
hosted OAuth endpoint above. Existing stdio users can continue with an API key:

```json
{
  "mcpServers": {
    "famulor": {
      "command": "npx",
      "args": ["-y", "famulor-mcp"],
      "env": { "FAMULOR_API_KEY": "your-api-key" }
    }
  }
}
```

</details>

<details>
<summary><b>Zed</b></summary>

`~/.config/zed/settings.json`

```json
{
  "context_servers": {
    "famulor": {
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://app.famulor.io/mcp"
      ],
      "command": "npx"
    }
  }
}
```

Add the server first, then complete the browser-based OAuth flow.
</details>

---

## What you can do

Once connected, your AI assistant discovers the current public tool catalog
directly from Famulor. The catalog covers, among other areas:

**Assistants** — create, update, delete AI voice agents · list voices, languages, LLM/multimodal models, TTS/STT providers · toggle inbound and conversation-ended webhooks

**History & calls** — inspect cross-channel history and transcripts · make and manage calls

**Campaigns** — create campaigns, manage retry rules and allowed-hours windows · start, stop and delete

**Audience** — manage contacts, tags, segments, suppression and campaign membership

**Knowledge bases** — create knowledge bases · upload website-scraped documents · update / delete

**Telephony** — phone numbers, number verification, assignments and SIP trunks

**Messaging & email** — WhatsApp, Instagram, Messenger, Telegram, Slack, Teams,
Discord, Google Chat, X, helpdesk and email conversation workflows

**WhatsApp** — list senders and templates · check 24h session window · send template or freeform messages

**Automations & operations** — flows, routines, dashboards, integrations,
webhooks, booking, workspace settings and account administration

Ask the assistant in plain English, e.g. *"Create a German sales assistant using GPT-4.1-mini and the Susi voice"*, *"Start campaign #42 and add these 50 leads"*, *"Show me all calls today where the goal wasn't reached."*

---

## How auth works

The canonical endpoint implements MCP OAuth discovery, authorization code with
PKCE, dynamic client registration and Client ID Metadata Documents. Your MCP
client opens Famulor in a browser, where you sign in, choose a workspace and
approve the requested scopes. API keys are also accepted for server-to-server
clients, but are not the Claude or ChatGPT connector path.

---

## Self-hosting

The canonical full-catalog server is part of the Famulor application and is not
implemented by this legacy standalone package. The code in this repository is
retained for existing self-hosted and npm users.

### Deploy to Vercel

```bash
git clone https://github.com/bekservice/Famulor-MCP.git
cd Famulor-MCP
vercel --prod
```

Set these env vars in the Vercel project:

| Variable      | Required | Value                                                |
| ------------- | -------- | ---------------------------------------------------- |
| `MCP_SECRET`  | yes      | `openssl rand -hex 32` — encrypts OAuth tokens.      |
| `MCP_ISSUER`  | rec.     | Your public URL, e.g. `https://mcp.example.com`.     |

Then point your domain at the deployment and you're live. See
[DEPLOYMENT.md](./DEPLOYMENT.md) for the full guide including stdio mode for
power users.

### Local dev

```bash
npm install
echo "MCP_SECRET=$(openssl rand -hex 32)" > .env
npm run dev:http
# server on http://localhost:8787
```

```bash
# health
curl http://localhost:8787/health

# OAuth metadata
curl http://localhost:8787/.well-known/oauth-authorization-server
```

---

## License

MIT