grantd

Name: grantd
Author: rafavecchi

本地服务

github.com/rafavecchi安全120 周前更新

代码仓库

关于 grantd

grantd 是面向 Agent 的可自托管 OAuth 令牌代理，让 Agent 代表用户调用第三方 API。它通过 MCP 工具管理授权和 API 请求，并将原始令牌留在 LLM 和调用方之外。

主要功能

01服务端加密保存 OAuth 令牌
02支持 Google、GitHub、Slack 和 Notion 的提供方注册表
03OAuth 授权、交换与刷新
04连接检查和提供方 API 代理
05缺少授权时返回连接链接

适用场景

01让 Agent 调用用户已连接的提供方 API
02连接缺失时引导用户完成授权

MCP 相关

它将 list_providers、check_connection、create_connect_link 和 call_provider 暴露为 MCP 工具。缺少授权时，call_provider 会返回 authorization_required 结果和连接链接。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "rafavecchi-grantd": {
      "command": "npx",
      "args": [
        "-y",
        "grantd-mcp"
      ],
      "env": {
        "GRANTD_API_KEY": "<GRANTD_API_KEY>",
        "GRANTD_BASE_URL": "<GRANTD_BASE_URL>",
        "GRANTD_END_USER": "<GRANTD_END_USER>"
      }
    }
  }
}

启动命令npx -y grantd-mcp

需要配置的环境变量

GRANTD_API_KEY密钥A Grantd secret key (sk_...). Treat it like a password.

GRANTD_BASE_URLBase URL of your Grantd broker (default http://localhost:8787).

GRANTD_END_USERDefault end-user id so tools don't need it passed each call.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmgrantd-mcp0.1.0stdio

工具

收录的工具列表 · 更新于 2 周前

此工具无需参数。

详细介绍

Grantd

面向 Agent 的 OAuth：一个极简、原生支持 MCP 的 OAuth 令牌代理，让 AI Agent 能够安全地代表用户调用第三方 API（Gmail、Slack、GitHub、Notion……）。令牌保存在服务端的保险库中，绝不会接触大模型。

技术栈：TypeScript · Hono · Postgres · 由声明式提供方注册表驱动的通用 OAuth2 · 信封加密（AES-256-GCM，密钥版本化）· 使用 Postgres advisory locks 处理令牌刷新并发（无需 Redis）。安全模型和问题报告方式见：SECURITY.md。

安全概览

Grantd 会将用户的 OAuth 令牌保存在保险库中，因此安全不是一项功能，而是产品本身。基本原则如下：

令牌静态加密 — 使用 AES-256-GCM 信封加密，每条记录使用新的 IV，并采用密钥版本化；同时采用失败即关闭策略（缺少密钥时拒绝写入，绝不会悄悄以明文存储）。
**令牌绝不会传给大模型或调用方。**代理会在网络边界注入访问令牌，并且只返回提供方的响应——原始令牌绝不会被序列化并返回。
API 密钥静态哈希存储（pbkdf2-sha256，使用 pepper）；原始 sk_ 密钥仅显示一次。
无 SQL 注入 — 每个查询都是参数化的 postgres.js 标签模板。
每个查询都按环境 ID 隔离租户；所有表均启用行级安全策略，因此 Postgres REST 层（如 Supabase/PostgREST）无法读取保险库。
OAuth state 和会话令牌均使用 256 位随机数；提供方支持时使用 PKCE (S256)。
由 Postgres 提供持久化的速率限制 — 认证路由按密钥限制，公共路由按 IP 限制。

这是一个由你自行运行的开源基础设施。我们如实记录了自托管的责任（密钥保管、TLS、用于抵御大流量 DoS 的边缘层/WAF）和已知限制，详见 SECURITY.md。如果你打算运行一个托管的多租户部署，并保管其他人的令牌，请先逐项检查 HOSTED-CHECKLIST.md。

提供方

提供方	状态
Google（Gmail、Calendar，……）	✅ 已完成端到端验证，包括令牌刷新
GitHub	✅ 已完成端到端验证
Slack	🧪 实验性 — 已提供配置，但尚未通过实际 OAuth 验证
Notion	🧪 实验性 — 已提供配置，但尚未通过实际 OAuth 验证

添加提供方只需添加数据，无需编写代码（见 src/providers.ts）。欢迎协助验证 Slack/Notion。

快速开始（开发）

npm install
npm run keygen            # prints an ENCRYPTION_KEYRING + API_KEY_SALT
cp .env.example .env      # then paste keygen output + your DATABASE_URL
npm run migrate           # apply SQL migrations
npm run dev               # start the broker on :8787

MCP 服务

将代理作为工具提供给 AI Agent（Claude Code / Cursor / Claude Desktop）： list_providers、check_connection、create_connect_link 和 call_provider。授权门控机制：如果 Agent 为尚未连接的用户调用 call_provider，服务会返回带有连接链接的 authorization_required 结果，而不是报错。

MCP 服务已作为 grantd-mcp 发布到 npm，因此你无需克隆此仓库即可使用——只需让 MCP 客户端连接到它（你需要先运行代理并提供密钥）。本地开发：npm run mcp（需要代理正在运行）；冒烟测试：npm run mcp:test。

添加到 Claude Code：

claude mcp add grantd \
  --env GRANTD_API_KEY=sk_... \
  --env GRANTD_BASE_URL=https://your-broker.example.com \
  --env GRANTD_END_USER=user-123 \
  -- npx -y grantd-mcp

或者在 Cursor / Claude Desktop 的 mcpServers 配置中：

{
  "mcpServers": {
    "grantd": {
      "command": "npx",
      "args": ["-y", "grantd-mcp"],
      "env": {
        "GRANTD_API_KEY": "sk_...",
        "GRANTD_BASE_URL": "https://your-broker.example.com",
        "GRANTD_END_USER": "user-123"
      }
    }
  }
}

目录结构

migrations/   SQL schema (Supabase/Postgres compatible)
scripts/      keygen + migrate helpers
src/
  config.ts   env loading + validation + keyring parse
  crypto.ts   envelope encryption + API-key hashing
  db.ts       postgres.js client
  providers.ts declarative provider registry (Google, GitHub, Slack, Notion)
  oauth.ts    generic OAuth2 client (authorize / exchange / refresh) driven by the registry
  server.ts   Hono app + routes (WIP)

支持 Markdown

登录后评论