MCP Server

The seven Model Context Protocol server lets AI assistants like Claude Desktop, Claude Code and Cursor interact with the seven.io API directly. It exposes SMS, RCS, voice, lookups, contacts and account management as more than 40 tools across 12 categories.

The server is distributed as the npm package @seven.io/mcp and runs locally via npx over the MCP stdio transport. The source is on GitHub.

Installation

npm install -g @seven.io/mcp

You can also skip the global install — npx @seven.io/mcp fetches the latest version on demand whenever the MCP client launches the server.

Authentication

The server supports two authentication methods. OAuth 2.0 with PKCE is recommended — it provides automatic token refresh, fine-grained scopes and stores tokens securely in your operating system's keychain. If both methods are configured, OAuth takes priority.

Option 1: OAuth 2.0 (recommended)

Run the login command once. It opens your browser, requests the necessary scopes (SMS, Voice, RCS, …) and stores the tokens.

npx @seven.io/mcp login

Other CLI commands:

# Show whether you are signed in
npx @seven.io/mcp status

# Remove the stored tokens
npx @seven.io/mcp logout

Option 2: API key (legacy)

Set the SEVEN_API_KEY environment variable. Create your key in the seven.io dashboard.

export SEVEN_API_KEY="your-api-key"

Headless or remote setups

The OAuth login flow needs a browser on the same machine that can reach 127.0.0.1:7177 / 9437 / 8659. If you run the MCP server on a headless box or via SSH without port forwarding, fall back to the API key (Option 2) — that path doesn't require a browser.

Quick start

Add the server to the configuration of your MCP client and restart the client.

Claude Desktop

Edit your claude_desktop_config.json:

With OAuth (recommended) — run npx @seven.io/mcp login first:

{
  "mcpServers": {
    "seven": {
      "command": "npx",
      "args": ["@seven.io/mcp"]
    }
  }
}

With an API key:

{
  "mcpServers": {
    "seven": {
      "command": "npx",
      "args": ["@seven.io/mcp"],
      "env": {
        "SEVEN_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add seven npx @seven.io/mcp

Cursor

Add the server to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "seven": {
      "command": "npx",
      "args": ["@seven.io/mcp"]
    }
  }
}

Available tools

The server provides more than 40 tools grouped by capability.

Messaging

Account

Lookup

Status & logbook

Phone numbers

Contacts

Groups

Subaccounts

Webhooks

Sender

Examples

Once the server is connected, you can ask the assistant in plain language. The MCP client picks the right tool automatically.

Send an SMS:

Send an SMS to +49170123456789 saying 'Order shipped — track at example.com/t/abc123'.

The assistant calls send_sms.

Check your balance:

What is my seven.io account balance?

The assistant calls get_balance.

Carrier lookup and RCS check:

Look up the carrier for +49170123456789 and tell me whether the number supports RCS.

The assistant chains lookup_mnp and lookup_rcs.

Debug logging

Set SEVEN_LOG_FILE to log every API request and response to a file. Useful when a tool call doesn't behave as expected.

{
  "mcpServers": {
    "seven": {
      "command": "npx",
      "args": ["@seven.io/mcp"],
      "env": {
        "SEVEN_API_KEY": "your-api-key",
        "SEVEN_LOG_FILE": "/tmp/mcp-seven-debug.log"
      }
    }
  }
}

Then tail the file:

tail -f /tmp/mcp-seven-debug.log

Resources

• GitHub repository
• npm package
• Model Context Protocol specification
• Issue tracker