内容
# grindr-mcp
一款适用于**非官方**Grindr API的[模型上下文协议](https://modelcontextprotocol.io)服务器。它允许MCP客户端（Claude Code、Claude Desktop等）登录Grindr并调用任何端点，内置API发现功能来自捆绑的OpenAPI规范。
它基于[`grindr.rs`](https://git.opengrind.org/open-grind/grindr.rs)构建，该模块与Grindr的交互方式与Android应用程序相同——相同的TLS/HTTP2指纹、头部顺序和设备身份——因此请求可以绕过Cloudflare。API表面来自[Open Grind](https://opengrind.org)项目的OpenAPI文档。
> ⚠️ **仅用于教育目的。** 本项目仅用于教育和研究API互操作性。它是**非官方**的，与Grindr无关，也不受Grindr授权或认可。自动访问可能会违反Grindr的使用条款。请仅使用您自己的帐户，并自行承担风险——您对如何使用它负有全部责任。
## 工具列表
| 工具 | 用途 |
| --- | --- |
| `grindr_login` | 使用电子邮件+密码登录。会话将被持久化和自动刷新。 |
| `grindr_logout` | 清除会话并将其从磁盘中删除。 |
| `grindr_session_status` | 检查会话是否活跃，以及设备摘要。 |
| `grindr_request` | 向任何端点发出身份验证请求（`method`、`path`，可选的JSON `body`）。返回状态码和响应体。 |
| `grindr_update_location` | 更新您的个人资料广播位置（`geohash`或`latitude`+`longitude`）。同时设置网格使用的固定位置。 |
| `grindr_browse_grid` | 使用筛选器浏览附近的个人资料（`photo_only`、`online_only`、`age_min/max`等）；位置来自geohash、lat/long或固定位置。 |
| `grindr_get_profile` | 通过`profile_id`查看用户的完整个人资料：生物、年龄、部落、标签、统计数据、社交媒体——照片媒体哈希值转换为CDN图片链接。 |
| `grindr_list_conversations` | 列出收件箱对话（最近的优先），带有`unread_only` / `favorites_only` / `online_now_only` / `right_now_only`筛选器和`page`。 |
| `grindr_get_messages` | 获取对话中的消息（`conversation_id`，可选的`page_key`用于较旧的消息）。不会标记为已读。 |
| `grindr_list_endpoints` | 列出OpenAPI规范中的端点，按`tag`和/或`search`筛选。 |
| `grindr_describe_endpoint` | 路径的完整详细信息：参数、请求/响应模式（内联`$ref`）。 |
| `grindr_list_tags` | 列出API标签（类别）以用作`tag`筛选器。 |
`grindr_update_location`、`grindr_browse_grid`、`grindr_get_profile`、`grindr_list_conversations`和`grindr_get_messages`是对常用端点的便捷包装；其他所有操作都可以通过通用`grindr_request`访问。
> ⚠️ `grindr_update_location`会更改您的个人资料在他人眼中的位置。在**英国**设置位置可能会锁定您的帐户，直到您提交年龄验证文件——请避免使用英国坐标。
典型流程：`grindr_login` → `grindr_list_conversations` → `grindr_get_messages`，或`grindr_list_tags` / `grindr_list_endpoints` → `grindr_describe_endpoint` → `grindr_request`用于其他所有操作。
## 安装（预编译二进制文件——无需Rust工具链）
每个标记版本都会发布由GitHub Actions构建的独立二进制文件，因此您不需要Rust或CMake来运行服务器。从[发布页面](https://github.com/aekrylov/grindr-mcp/releases)获取您所在平台的存档：
| 平台 | 资产 |
| --- | --- |
| macOS，Apple Silicon | `grindr-mcp-aarch64-apple-darwin.tar.gz` |
| macOS，Intel | `grindr-mcp-x86_64-apple-darwin.tar.gz` |
| Linux，x86-64 | `grindr-mcp-x86_64-unknown-linux-gnu.tar.gz` |
```sh
# 示例：macOS Apple Silicon
tar -xzf grindr-mcp-aarch64-apple-darwin.tar.gz
sudo mv grindr-mcp-aarch64-apple-darwin/grindr-mcp /usr/local/bin/
xattr -d com.apple.quarantine /usr/local/bin/grindr-mcp 2>/dev/null || true # macOS Gatekeeper
```
每个存档都有一个匹配的`.sha256`，您可以使用`shasum -a 256 -c`进行验证。
## 从源代码构建
如果您想自己构建它，则需要此操作。需要Rust和CMake（后者用于TLS指纹的BoringSSL）。
```sh
brew install rust cmake # 如果您没有它们
cargo build --release # 二进制文件位于target/release/grindr-mcp
```
## 配置
服务器通过**stdio**进行MCP通信。将您的客户端指向已编译的二进制文件。
### Claude Code
```sh
claude mcp add grindr -- /Users/anth/prog/grindr-mcp/target/release/grindr-mcp
```
### Claude Desktop / 通用`mcpServers`配置
```json
{
"mcpServers": {
"grindr": {
"command": "/Users/anth/prog/grindr-mcp/target/release/grindr-mcp"
}
}
}
```
然后要求客户端登录（它将使用您的凭证调用`grindr_login`），或在状态文件中预先设置一个会话。
## 状态和密钥
设备身份和会话存储在：
- 如果设置了`$GRINDR_MCP_STATE`，否则
- `<config dir>/grindr-mcp/state.json`（在macOS上：`~/Library/Application Support/grindr-mcp/state.json`）。
文件以`0600`权限写入。它包含 bearer token — 将其视为密钥。保持相同的设备跨运行可能会减少Cloudflare的拦截，因此一旦创建，生成的`DeviceInfo`就会被重复使用。
## 请求的工作原理
`grindr_request`直接映射到捆绑的`openapi.json`中的端点。例如：
- `GET /v3/me/profile` — 您自己的个人资料
- `GET /v4/cascade` — 浏览网格
- `GET /v5/rightnow/feed` — Right Now feed
会话令牌（`Authorization: Grindr3 <jwt>`）、设备头部和okhttp TLS/HTTP2指纹均自动应用；令牌在过期前刷新，并在`401`时主动刷新。
## 布局
- `src/main.rs` — 服务器结构体、共享请求帮助函数、`ServerHandler`和入口点。
- `src/tools/generic.rs` — 通用发现/请求工具（`grindr_request`、`grindr_list_endpoints`、`grindr_describe_endpoint`、`grindr_list_tags`）。
- `src/tools/endpoints.rs` — 端点特定工具（身份验证、对话、消息、位置、网格、个人资料）。
- `src/openapi.rs` — 发现帮助函数，基于捆绑的规范。
- `src/geohash.rs` — 位置工具的geohash编码。
- `src/state.rs` — 磁盘设备 + 会话 + 固定位置持久性。
- `openapi.json` — Grindr OpenAPI规范（来自<https://opengrind.org/openapi.json>）。
两组工具是单独的`#[tool_router]`块（`generic_router`和`endpoint_router`），在`GrindrServer::new`中合并。传输crate [`grindr.rs`](https://git.opengrind.org/open-grind/grindr.rs)是一个固定的git依赖项。
## 致谢
- [`grindr.rs`](https://git.opengrind.org/open-grind/grindr.rs) — 传输。
- [Open Grind](https://opengrind.org) — API参考和OpenAPI规范。
