npm package: @osmapi/mcp-server-osmtalk
Description: MCP server for OsmTalk — make phone calls via Claude Desktop using voice AI agents
Latest version: 0.4.2

# @osmapi/mcp-server-osmtalk

MCP server for [OsmTalk](https://osmtalk.com) — make phone calls and manage voice AI agents via Claude Desktop.

## What You Can Do

- **Make phone calls** — "Call John and tell him I'm running late"
- **View call history** — "Show me today's calls"
- **Read transcripts** — "What did the last caller say?"
- **Check analytics** — "How many calls this week?"
- **List agents & numbers** — "What agents do I have?"

## Quick Start

### 1. Get an API Key

OsmTalk dashboard → **Settings** → **API Keys** → Create with **Calls** scope enabled.

### 2. Configure Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "osmtalk": {
      "command": "npx",
      "args": ["-y", "@osmapi/mcp-server-osmtalk"],
      "env": {
        "OSMTALK_API_KEY": "osm_your_api_key_here"
      }
    }
  }
}
```

Windows: `%APPDATA%\Claude\claude_desktop_config.json`

### 3. Restart Claude Desktop

You should see OsmTalk tools available (7 tools).

## Available Tools

| Tool | Description |
|------|-------------|
| `list_agents` | List voice agents and their status |
| `list_phone_numbers` | List outbound-capable phone numbers |
| `list_calls` | Call history with filters (date, status, agent, channel) |
| `get_dashboard` | Analytics: total calls, today, this week, success rate, top agents |
| `make_call` | Make outbound call with instruction + openingMessage |
| `get_call_status` | Poll active call status |
| `get_call_result` | Full transcript, metrics, recording of any call |

## How Calls Work

```
You: "Call +91-98xxx and tell them I can't make it to today's meeting"
  |
Claude generates:
  instruction: "Inform them you can't attend today's meeting, ask to reschedule"
  openingMessage: "Hi, this is Maya calling on behalf of Kesavan. I'm calling
                   to let you know that Kesavan won't be able to make it to
                   today's meeting. Would it be possible to reschedule?"
  |
OsmTalk API → Bot spawns → SIP dials → Phone rings
  |
Person picks up → Hears openingMessage immediately (no delay)
  |
Full two-way conversation happens (person can respond, negotiate, ask questions)
  |
Call ends → Transcript saved
  |
Claude: "They said tomorrow at 2 PM works. Meeting rescheduled."
```

### instruction vs openingMessage

| Parameter | Purpose | Example |
|-----------|---------|---------|
| `instruction` | Agent's objective (system prompt) | "Cancel the 3pm appointment, get confirmation" |
| `openingMessage` | What the agent SAYS when person answers (TTS, instant) | "Hi, this is Maya calling on behalf of Kesavan. I need to cancel the 3pm appointment today." |
| `callerName` | Who the agent is calling for | "Kesavan" |

The `openingMessage` plays immediately as one smooth TTS output — no LLM delay. Claude generates it as natural human dialogue.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `OSMTALK_API_KEY` | Yes | API key with `calls` scope (starts with `osm_`) |
| `OSMTALK_API_URL` | No | Defaults to `https://api.osmtalk.com` |

## Requirements

- Node.js 20+
- OsmTalk account with voice agent + outbound phone number configured
- API key with `calls` scope

## Links

- [OsmTalk](https://osmtalk.com)
- [MCP Protocol](https://modelcontextprotocol.io/)
- [npm Package](https://www.npmjs.com/package/@osmapi/mcp-server-osmtalk)

## License

MIT