Gosar MCP Server

一个 MCP 服务器，让 Claude 代表用户调用 Gosar API，通过 Gosar 的 OAuth 2.0 + PKCE 流程进行身份验证。

它充当一座桥梁：

• 对于 Claude（MCP 客户端），它表现得像一个完整的 OAuth 授权服务器——处理动态客户端注册并颁发自己的短期令牌。

• 对于 Gosar，它是唯一预先注册的 OAuth 客户端（公共，仅 PKCE），执行 Gosar 集成指南中描述的真实授权码 + PKCE 交换。

先决条件

• Python 3.11+

• 一个在 Gosar 团队注册的 Gosar OAuth 客户端（参见集成指南中的“我们需要你提供什么”）——你需要一个 client_id 和一个已批准的重定向 URI。

• ngrok（或类似工具），如果你想测试真实的 Gosar API——Gosar 的重定向 URI 必须是 HTTPS 且完全匹配，Claude 也需要一个 HTTPS URL 来连接远程 MCP 服务器。

Related MCP server: Strava MCP Server

1. 安装依赖

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. 配置 .env

将你拥有的值复制到项目根目录的 .env 中：

# Real values from the Gosar team
GOSAR_API_BASE_URL=https://api.gosar.example
GOSAR_CLIENT_ID=your-registered-client-id
GOSAR_SCOPES=applications.read applications.write

# Your server's own public HTTPS URL (e.g. your ngrok URL). Gosar's registered
# redirect_uri must be exactly this + GOSAR_REDIRECT_PATH.
MCP_PUBLIC_BASE_URL=https://your-tunnel.ngrok-free.app
GOSAR_REDIRECT_PATH=/gosar/callback

MCP_HOST=0.0.0.0
MCP_PORT=8000

# Generate once and keep stable — see below
JWT_SIGNING_KEY=

生成签名密钥（Gosar 是公共客户端，没有密钥，因此无法自动派生——这是必需的）：

python -c "import secrets; print(secrets.token_urlsafe(32))"

将输出粘贴到 JWT_SIGNING_KEY 中。在重启之间保持相同，否则每个已连接的用户都会被登出。

3. 通过 HTTPS 暴露你的服务器（用于真实 Gosar 测试）

Claude 和 Gosar 都要求 HTTPS。在另一个终端中：

ngrok http 8000

将 https://...ngrok-free.app URL 复制到 .env 中的 MCP_PUBLIC_BASE_URL，并将 {MCP_PUBLIC_BASE_URL}/gosar/callback 发送给 Gosar 团队作为你注册的重定向 URI。

4. 运行服务器

source .venv/bin/activate
python main.py

你应该看到：

Starting MCP server 'Gosar' with transport 'http' on http://0.0.0.0:8000/mcp
Uvicorn running on http://0.0.0.0:8000

代码更改时自动重载

python main.py 不会重载——mcp.run() 会阻塞并拥有自己的 uvicorn 进程，无法交给文件监视重载器。对于开发，请直接在 uvicorn 下运行 gosar_mcp/asgi.py 中的 ASGI 应用：

uvicorn gosar_mcp.asgi:app --reload --reload-include ".env" --host 0.0.0.0 --port 8000

• --reload 会在任何 .py 文件更改时重启工作进程。

• --reload-include ".env" 也会在你编辑 .env 时重启它（uvicorn 默认只监视 Python 文件，环境变量只在进程启动时读取一次，因此如果没有此标志，编辑 .env 需要手动重启）。

• 保持端口与你的 ngrok 隧道指向的端口同步。

5. 检查 OAuth 连接是否正常

在服务器运行时，确认发现元数据已提供：

curl -s http://127.0.0.1:8000/.well-known/oauth-authorization-server | python3 -m json.tool

你应该在 scopes_supported 中看到 applications.read/applications.write，并且 S256 是唯一的 PKCE 方法。

6. 将其连接到 Claude

在 Claude 的连接器设置中，添加一个远程 MCP 服务器，指向：

https://your-tunnel.ngrok-free.app/mcp

Claude 将在此服务器上注册为 OAuth 客户端，将用户重定向到同意页面，然后通过 Gosar 的真实 Google 登录 + 同意屏幕，最后带着活动连接回到这里。让 Claude 调用 whoami 工具以确认它已作为预期的 Gosar 账户进行身份验证。

备注

• 令牌存储（客户端注册 + 加密的上游 Gosar 令牌）默认使用操作系统合适的加密文件存储——本地开发无需额外设置。有关在生产环境中将其指向其他后端的说明，请参阅 gosar_mcp/auth.py。

• gosar_mcp/tools.py 的 /applications 端点路径是占位符——集成指南只指定了 OAuth 层，没有指定 Applications REST API 的形状。请与 Gosar 团队确认真实的路径/负载，并在那里进行调整。