convez.ai
MCP ServerIntegração & APIsIntermediário
joethefisher

Outreach API MCP

joethefisher/outreach-api-mcp

MCP server read-only para Outreach — prospects, contas, sequências e mais

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP independente para integração com a plataforma Outreach, expondo 21 ferramentas de leitura para consultar prospects, contas, sequências, templates, snippets, tarefas, mails e logs de auditoria. Conecta Claude Desktop ou qualquer cliente MCP direto à sua workspace Outreach via OAuth, sem afiliação oficial.

Instalação

$npx convez-ai joethefisher/outreach-api-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 3 meses
Versão
v0.1.2
Issues abertas
7
Contribuidores
2

Casos de uso

  • Consultar e analisar dados de prospects e contas em tempo real durante workflows de vendas
  • Auditar sequências de email e templates sem sair do Claude
  • Revisar logs de auditoria e atividades da workspace para conformidade

Veredito

Integração sólida e bem-revisada (v0.1.2) que expõe a API Outreach de forma segura como MCP. Read-only por design e com autenticação OAuth robusta — ideal para quem já usa Outreach e quer consultá-lo via Claude sem ferramentas de escrita.

README

A tradução para o português deste README ainda está na fila.

Outreach API MCP

A Model Context Protocol server for Outreach. You give it your own Outreach OAuth credentials, an MCP client like Claude Desktop talks to it over stdio, and you get 21 read-only tools for querying prospects, accounts, sequences, templates, snippets, tasks, mailings, and audit logs from your own workspace.

Independent integration. Not affiliated with, endorsed by, or sponsored by Outreach. You comply with Outreach's API terms; this code just speaks the protocol.

Status

v0.1.2. The MCP server is in outreach-worker/ and runs over stdio. Read-only by design: no POST, PATCH, or DELETE, and no write scopes get requested. CI runs on Node 20 and Node 22 against 290 unit and integration tests. Three review passes have landed: the initial scaffold review, the v0.1.1 blocker-fix verification, and the v0.1.2 fast-follows (correctness, security hardening, test coverage, and design cleanup — see commit history on main for the per-finding trail).

Prerequisites

Two things:

  1. Node.js, version 20 or newer.
  2. An Outreach OAuth application in your own Outreach workspace. You register this once and reuse it forever.

Registering an Outreach OAuth app

You do this once per workspace. The server uses these credentials to mint per-user refresh tokens, and credentials never get shared across users of your workspace.

The steps:

  1. Sign in to Outreach as a user with admin permission for API integrations.
  2. Open Settings (gear icon), then Integrations, then API Access, then "Your applications."
  3. Click the button to create a new app.
  4. Fill in the form:
    • Name: anything descriptive, like outreach-api-mcp (local).
    • Description: optional.
    • Redirect URIs: add http://127.0.0.1:8765/callback. If you later change the port via OUTREACH_OAUTH_REDIRECT_PORT, the URI here has to match exactly.
    • Scopes: pick every scope listed in outreach-worker/src/auth/scopes.ts. All of them end in .read. If you grant fewer, the tools that need a missing one will return a scopeMissing envelope and the agent will tell you which.
  5. Save the app.
  6. Copy the Application ID into OUTREACH_CLIENT_ID and the Application Secret into OUTREACH_CLIENT_SECRET. Outreach will not show the secret again, so put it somewhere safe.

A couple of gotchas. If the API Access page is hidden in your UI, an admin needs to grant you "Manage API Integrations" first. And the redirect URI has to match exactly, down to scheme, host, and port. http://127.0.0.1 (not localhost) is the right value; Outreach accepts it as loopback per RFC 8252.

Install

Two paths. Pick whichever feels more natural.

From a tagged release tarball (no clone required; treats this like a normal npm dependency):

npm install -g https://github.com/joethefisher/outreach-api-mcp/releases/download/v0.1.2/outreach-api-mcp-0.1.2.tgz

That gives you the outreach-api-mcp binary on your PATH plus the bundled dist/. Skip ahead to the bootstrap section.

From source (if you want to read the code, contribute, or run on an unreleased commit):

git clone https://github.com/joethefisher/outreach-api-mcp.git
cd outreach-api-mcp/outreach-worker
npm ci
npm run build

Bootstrap

# Put your app credentials in ../.env first (the bootstrap script reads it).
cp ../.env.example ../.env  # then edit OUTREACH_CLIENT_ID / SECRET

# One-time browser consent flow. Captures the refresh token.
npm run bootstrap:oauth

What bootstrap:oauth does, in order: opens your browser, walks you through the Outreach consent screen, captures the redirect on a local loopback HTTP server, exchanges the code for a refresh token, persists it to the on-disk cache, and prints an .env block on success. Copy that block into your .env (or wherever your MCP client sources env from). That is the whole setup.

Wiring into an MCP client

Once you have all three credentials, point your MCP client at the built server. The bootstrap step is only needed once; from this point on the credentials live in your MCP client's config and the on-disk token cache.

For Claude Desktop, find claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json) and add an entry:

{
  "mcpServers": {
    "outreach": {
      "command": "node",
      "args": ["/absolute/path/to/outreach-api-mcp/outreach-worker/dist/index.js"],
      "env": {
        "OUTREACH_CLIENT_ID": "...",
        "OUTREACH_CLIENT_SECRET": "...",
        "OUTREACH_REFRESH_TOKEN": "..."
      }
    }
  }
}

Fully quit and reopen Claude Desktop (a window reload is not enough — the MCP transport only restarts on app launch). The 21 tools below will show up in the tool picker. The server reads its configuration from the env you provide in this config block, not from any .env file on disk.

For other MCP clients, the contract is the same: spawn node dist/index.js as a subprocess with the three env vars set, and talk to it over stdio.

Configuration

Everything is environment variables. .env.example has the full list. The minimum:

VariablePurpose
OUTREACH_CLIENT_IDOAuth client ID from your app
OUTREACH_CLIENT_SECRETOAuth client secret from your app
OUTREACH_REFRESH_TOKENLong-lived refresh token from bootstrap:oauth. Seeds the on-disk cache on first run; after that the cache is the source of truth.

Available MCP tools

21 tools across five categories: 19 capability tools and 2 escape hatches. Schemas are in outreach-worker/src/index.ts if you want to read them directly.

CategoryTools
Prospects and AccountssearchProspects, getProspectProfile, searchAccounts, getAccountProfile
SequencessearchSequences, getSequenceProfile, getProspectSequenceHistory, analyzeSequencePerformance, compareSequences
Templates and SnippetssearchTemplates, getTemplate, searchSnippets, getSnippet
Activity and AuditgetOpenTasks, getRecentMailings, getTeamRoster, getUserActivity, getAuditLog
DraftingdraftEmail (returns a context bundle; never sends mail)
Escape hatchesoutreachQuery, outreachGetById

Read-only invariant

The part I want to be very explicit about. The server is read-only. No POST, no PATCH, no DELETE. The HTTP client hardcodes GET on every call, and there is no path through any tool that mutates Outreach state. Only .read OAuth scopes are requested. Even draftEmail only returns context; the model composes the email in chat for you to paste into Outreach yourself.

If you find a tool that violates this, that is a bug. Open an issue.

Security model

SECURITY.md has the full threat model. Briefly:

  • No telemetry. No outbound network calls beyond Outreach API endpoints.
  • All logging goes to stderr only. Stdout is reserved for MCP JSON-RPC frames, and mixing them up would corrupt the transport, which is why it is enforced by lint and asserted in tests.
  • OAuth tokens live in an on-disk cache with 0600 permissions, in $XDG_CONFIG_HOME/outreach-api-mcp/. The parent directory is 0700.
  • Refresh tokens rotate; the latest one always gets written back to cache.
  • Tokens, PII, and message bodies are never logged. The structured logger redacts on the way out.
  • Scope minimization: only the 19 read scopes that the tools actually need.

Standards

This codebase commits to a quality bar in STANDARDS.md. PRs get reviewed against it. The short version is strict TypeScript everywhere, integration tests for tool blocks, and no features the task did not request.

License

Apache 2.0.

Ver o original no GitHub

Bom para

Relacionados