open-connector README

The project's README from github.com/oomol-lab/open-connector. As one markdown file: README.md.

OpenConnector - Connect Once. Use Everywhere.

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Русский | Français | Español

License: Apache-2.0 Node.js 22+ Cloudflare compatible MCP OpenAPI

Providers Actions

OpenConnector is an open-source connector gateway for AI agents and an alternative to Pipedream/Composio. Connect user app accounts once, then expose a shared catalog of 1,000+ providers and 10,000+ prebuilt Actions to agents and applications.

OOMOL Self-hosted More platforms
Managed OAuth and hosted runtime, ready to use. No deployment or OAuth app setup. Run locally or on your own infrastructure with Docker or Node.js. You manage storage and OAuth apps. Cloudflare, Fly.io, RepoCloud, nibrun, and more.
🚀 OOMOL Hosted Self-host More platforms

Use the Connector SDK from app code, oo CLI as the local-agent relay, MCP from agent hosts, HTTP/OpenAPI from custom clients, and the Web Console for administration and debugging.

What It Provides

Where It Fits

OpenConnector fits products where agents need durable access to the tools users already use, without handing provider credentials to the agent process.

Developer Tools

Tool Purpose
Connector SDK Thin TypeScript HTTP client. Use OpenConnector for self-hosted runtimes, or Connector / ProjectConnector for OOMOL-hosted personal and SaaS end-user connections.
oo CLI Local agent relay for connector Actions. oo connector can search, inspect, and run Actions against OOMOL-hosted or self-hosted OpenConnector runtimes.
MCP Expose app Actions to MCP-capable agent hosts through http://localhost:3000/mcp.
HTTP / OpenAPI Call /v1/actions/* directly or inspect the generated /openapi.json document.

Endpoint details, response envelopes, auth headers, MCP tools, and Action guide examples are in docs/runtime-api.md.

Dashboard Preview

OpenConnector ships with a local Dashboard for browsing connectors, configuring credentials, creating runtime tokens, and inspecting runtime usage.

Connector Catalog

Use the connector catalog to see available services, search for providers, and open their Actions and credential setup from one place.

OpenConnector connector catalog dashboard

Usage Overview

Use the Overview page after deployment to monitor runtime readiness, available providers, executable Actions, recent failures, tool call trends, and recent calls.

OpenConnector runtime overview dashboard

Provider names and trademarks belong to their respective owners and are used only for identification and interoperability.

How It Works

flowchart LR
  Agent["AI Agent / App"] -->|"SDK / CLI / MCP / HTTP"| Gateway["OpenConnector Gateway"]
  Gateway --> Auth["Credential & OAuth Boundary"]
  Gateway --> Catalog["Provider Catalog"]
  Gateway --> Actions["Open-source Action Executors"]
  Gateway --> Policy["Tokens, Scopes, Allow/Block Policy"]
  Gateway --> Logs["Run Logs"]
  Actions --> Providers["1,000+ Providers"]
  Console["Web Console"] --> Gateway
  Cloudflare["Cloudflare Workers, D1, R2"] -. deploy .-> Gateway

Apps and agents discover Actions, inspect schemas and scopes, select a connection alias, and execute through the gateway. Provider secrets stay behind the runtime boundary; agents receive the metadata, safe account labels, and execution results needed for the run.

Usage Paths

Path Best for Includes
Open-source self-host Developers and teams that want full control Local Docker or Node runtime, SQLite or PostgreSQL state, local or S3-compatible transit files, MCP, HTTP, OpenAPI, and Web Console
Kubernetes (Helm) Teams that run their own clusters Hardened Helm chart with PVC-backed SQLite or PostgreSQL plus migration hooks, Ingress, autoscaling, and NetworkPolicy toggles
OOMOL Teams that want users to authorize accounts immediately OOMOL-provided OAuth apps, monthly included Connect credits, and hosted runtime infrastructure; the same provider and Action contracts keep a path open to later private or self-hosted deployment

Quick Start

[!NOTE] This starts a self-hosted runtime. OAuth providers require OAuth client credentials from apps you register with those providers. To let users authorize supported providers without setting up your own OAuth apps, use OOMOL-hosted connectors.

Start the runtime from the published image with Docker Compose:

docker compose up

This pulls ghcr.io/oomol-lab/open-connector:latest. To build from source instead:

docker compose -f docker-compose.yml -f docker-compose.build.yml up --build

Open the local console and generated API reference:

http://localhost:3000
http://localhost:3000/docs

Run a no-auth Action to verify the runtime:

curl -s -X POST http://localhost:3000/v1/actions/hackernews.get_top_stories \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

See docs/quickstart.md for the full local setup, first provider connection, OAuth flow, and runtime settings.

Connect a Provider

GitHub is the simplest credentialed example because it can use a personal access token:

curl -s -X PUT http://localhost:3000/api/connections/github \
  -H 'content-type: application/json' \
  -d '{"authType":"api_key","values":{"apiKey":"github_pat_..."}}'

curl -s -X POST http://localhost:3000/v1/actions/github.get_current_user \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

For OAuth2 apps, named connections, credential encryption, token refresh, and action policies, see docs/credentials.md and docs/configuration.md.

Web Console

For npm-based local development, open http://localhost:5173; the Web Console dev server proxies API requests to the runtime on http://localhost:3000. For Docker or a built Node runtime, the console is served from http://localhost:3000.

The console supports provider browsing, API key and OAuth client configuration, runtime token creation, Action schema inspection, Action debugging, recent run review, and access to the generated OpenAPI and MCP metadata.

PostgreSQL Runtime Storage

The Node runtime uses SQLite by default and can use PostgreSQL 15 or newer when OOMOL_CONNECT_DATABASE_URL is configured. PostgreSQL migrations are explicit: run npm run runtime:migrate before starting a version with pending migrations. Server startup only checks schema readiness and never applies PostgreSQL DDL. See docs/configuration.md for configuration, permissions, TLS, and multi-instance requirements. The Docker image exposes the same runner as its migrate subcommand; see docs/docker-ghcr.md.

Docker Image (GHCR)

Run OpenConnector from a prebuilt image on GitHub Packages (GHCR): ghcr.io/oomol-lab/open-connector. Use latest for the newest release, a pinned released version for production, or tip for the latest main build.

See docs/docker-ghcr.md for tags, pulling, and running.

Build a Desktop Agent with Wanta

OpenConnector and Wanta are two open-source projects for AI Agents in the OOMOL ecosystem. OpenConnector connects Agents to external services such as Gmail, Slack, and Notion. Wanta provides a complete desktop Agent application powered by OpenCode and uses OpenConnector to work with connected SaaS services.

Issues and pull requests are welcome.

Documentation

Development

Use Node.js 22 or newer:

npm install
npm run dev

The local API runtime listens on http://localhost:3000. The Web Console dev server listens on http://localhost:5173 and proxies API requests to the runtime.

Before opening a pull request:

npm run fix-check
npm test

Provider code lives under src/providers/<service>. See CONTRIBUTING.md for provider contribution rules.

License Scope

Unless otherwise noted, the source code, scripts, generated project scaffolding, tests, and documentation authored for this repository are licensed under the Apache License, Version 2.0. See LICENSE.txt.

The Apache-2.0 license for this repository does not grant rights to third-party products, providers, apps, APIs, trademarks, service marks, trade names, logos, icons, brand assets, documentation, screenshots, or other copyrighted materials owned by their respective holders.

Provider and app names, metadata, links, scopes, permissions, and optional logos/icons are included only to identify services and enable interoperability. All third-party brand and product rights remain with their respective owners. Inclusion in this catalog does not imply endorsement, sponsorship, partnership, certification, or verification by those owners.

If you contribute provider metadata or assets, only submit material you have the right to submit. Prefer linking to official public assets instead of copying brand files into this repository.

Community

Please keep issues and pull requests focused, respectful, and actionable. Participation in this project is governed by CODE_OF_CONDUCT.md.

Support OpenConnector

If OpenConnector is useful to you, giving it a ⭐ helps more developers discover the project.

How to star OpenConnector on GitHub

Contributors

Thanks to everyone who has helped build OpenConnector. Want to join them? See CONTRIBUTING.md.

OpenConnector contributors

Star History

Star history

open-connector (oomol-lab/open-connector)

Searching Database…

6K ·GitHub
Open-connector
Что это такое?OpenConnector — это шлюз коннекторов с открытым исходным кодом, который позволяет ИИ-агентам проходить аутентификацию и вызывать более 1000 SaaS-провайдеров (GitHub, Gmail, Notion, Slack, BigQuery и др.) через общий каталог готовых Actions. Это открытая альтернатива Pipedream и Composio.
Это шлюз, который я запускаю сам, или облачный сервис, к которому я просто обращаюсь?И то, и другое: можно развернуть его локально или на собственной инфраструктуре с помощью Docker или Node.js и самостоятельно управлять хранилищем и OAuth-приложениями, либо использовать размещенную среду выполнения OOMOL с управляемым OAuth. В обоих режимах контракты провайдеров и Actions одинаковые.
Как его запустить?Запустите самостоятельно развернутую среду выполнения через Docker Compose, который загружает образ ghcr.io/oomol-lab/open-connector, или соберите ее из исходного кода; затем откройте локальную Web Console и сгенерированный справочник API для настройки.
Что нужно перед подключением OAuth-провайдера?Нужны учетные данные OAuth-клиента из приложения, которое вы сами регистрируете у каждого провайдера, если только вы не используете коннекторы, размещенные OOMOL, которые предоставляют готовые OAuth-приложения. GitHub — самый простой случай, так как для аутентификации достаточно персонального токена доступа.
Есть ли подводные камни при установке, если перейти на PostgreSQL?Миграции PostgreSQL не выполняются автоматически: нужно выполнить 'npm run runtime:migrate' перед запуском версии с незавершенными миграциями, поскольку при старте сервера проверяется только готовность схемы, а сам DDL он никогда не применяет.
Как агенты и приложения на самом деле взаимодействуют с ним?Через тот интерфейс, который подходит вашему стеку: TypeScript Connector SDK из кода приложения, CLI 'oo' как локальный ретранслятор для агентов, MCP для хостов агентов с поддержкой MCP или прямые вызовы HTTP/OpenAPI, а также Web Console для администрирования и отладки.
Видят ли агенты мои исходные учетные данные провайдеров?Нет, секреты провайдеров остаются за границей среды выполнения; агенты получают только метаданные Actions, безопасные метки аккаунтов и результаты выполнения, необходимые для запуска.
Что на самом деле покрывает лицензия Apache-2.0 в этом проекте?Лицензия Apache-2.0 распространяется на исходный код репозитория, скрипты, каркас, тесты и документацию, но не предоставляет никаких прав на сторонних провайдеров, их товарные знаки, логотипы или фирменные материалы, включенные в каталог исключительно для идентификации.
Можно ли развернуть это в Kubernetes?Да, есть защищенный Helm-чарт с хранением состояния на PVC в SQLite или PostgreSQL, хуками миграций, Ingress, автомасштабированием и переключателями NetworkPolicy для команд, которые управляют собственными кластерами.
Что такое Wanta и как он связан с OpenConnector?Wanta — отдельное настольное приложение ИИ-агента с открытым исходным кодом на базе OpenCode, которое внутри использует OpenConnector, чтобы его агент мог работать с подключенными SaaS-сервисами, такими как Gmail, Slack и Notion.
Какие варианты хранения поддерживает среда выполнения?Среда выполнения Node по умолчанию использует SQLite и может переключиться на PostgreSQL 15+; промежуточные файлы могут храниться либо локально, либо в S3-совместимом хранилище.
Можно ли попробовать без предварительной настройки OAuth?Да, быстрый старт включает запуск Action без аутентификации на локальной среде выполнения, чтобы проверить, что всё работает, перед подключением реального провайдера с учетными данными.
What are similar projects?trueforge, executor, anythingmcp, goshen-email, buzzkit, casdoor, open-webui, electric
Which topics is it in?agent-tools, api-gateway, openapi, cloudflare-workers, oauth, model-context-protocol, kubernetes, postgresql, docker-compose, sdk, cloud, database
Creator
oomol-lab
Size
32.8 MB
Stars
6K
Updated
CommitOct 17Releasev1.9.0Oct 15
Age
3mo
Commits · 90 Days