outdooriq-mcp

OutdoorIQ MCP — 户外休闲智能

基于 12 个州的 72,000 多个美国湖泊和 293,000 多条投放记录。

OutdoorIQ MCP 是一款付费 MCP 服务，可向 AI Agent 提供湖泊状况、鱼类投放记录、钓鱼适宜度评分和实时天气。它基于 CastIQ 数据集构建（该数据集还为 fishing-seo.pages.dev 和 CastIQ 目录 API 提供数据）。

如果你正在构建行程规划助手、钓鱼应用、旅行礼宾服务或需要推荐湖泊、根据近期投放记录安排游览时间，或按需获取钓鱼报告的户外品牌 Agent，这就是你要接入的数据层。

对于面向消费者的 AI 产品，OutdoorIQ 只需一个经过身份验证的 MCP 端点，就能替代十个数据源的 ETL；费用也可预测，不必担心周末流量激增后收到意外的 S3 账单。

---

定价

层级	价格	限制
免费	$0	outdooriq-dev-key-001，每天 50 次调用
Pro	$14/mo	不限次数
按量付费	$0.01/call	无月度最低消费

产品列表和结账：https://mcpize.com/outdooriq-mcp

---

在 Claude 中安装

线上 URL： https://mcp.castiq.net/mcp（Railway 备用地址：https://web-production-9b8950.up.railway.app/mcp）

最快的方式是使用 mcp-remote 作为 stdio→HTTP 桥接：

claude mcp add outdooriq-mcp -- npx -y mcp-remote \
  https://mcp.castiq.net/mcp \
  --header "X-API-Key:outdooriq-dev-key-001"

或者手动配置：

{
  "mcpServers": {
    "outdooriq-mcp": {
      "url": "https://mcp.castiq.net/mcp",
      "headers": { "X-API-Key": "outdooriq-dev-key-001" }
    }
  }
}

Anthropic MCP Registry 条目： io.github.bch1212/outdooriq-mcp — 已列入 https://registry.modelcontextprotocol.io。

Agent 提示词示例：

“帮我找出芝加哥附近最适合本周末去的 5 个鳟鱼湖。”

Agent 会调用 get_nearby_lakes（使用芝加哥的纬度/经度，半径 200mi），通过 get_top_lakes 按 species: trout 筛选，然后为最匹配的湖泊获取 get_fishing_report_summary。

---

工具参考

工具	参数	返回内容
search_lakes	name?, state?, county?, min_acres?, max_acres?, limit?	匹配湖泊的列表
get_lake_details	lake_id	坐标、面积、深度、鱼类和设施
get_stocking_data	lake_id?, species?, year?, limit?	近期鱼类投放记录
get_fishing_score	lake_id	0-100 分，并附评分区间明细
get_nearby_lakes	lat, lng, radius_miles?, min_score?, limit?	GPS 附近的湖泊，按评分排序
get_weather_for_lake	lake_id	当前天气 + 7 天预报（Open-Meteo）
get_top_lakes	state?, species?, limit?	评分最高的湖泊
get_stocking_schedule	state?, species?, month?, limit?	最新的匹配记录，可作为规划参考
search_species	state?, season?	正在投放的鱼类
get_fishing_report_summary	lake_id	自然语言报告

---

架构

client (Claude / agent)
        │  HTTP POST /mcp  (JSON-RPC 2.0)
        ▼
   FastAPI app (server.py)
        │  X-API-Key auth + per-day rate limiter
        ▼
  Tool registry (10 tools)
        │
        ▼
  db.connection.py  ──────┐
        │ Postgres mode  │  → CastIQ Postgres (72k lakes, 293k stockings)
        │ SQLite fallback│  → bundled seed (100+ lakes, ~150 stockings)
        ▼
  tools.* (lakes, stocking, scoring, weather, reports)
        │
        ▼
  Open-Meteo (no key)

Postgres 与 SQLite 模式

服务会在启动时选择后端：

1. 如果设置了 DATABASE_URL，则尝试调用 asyncpg.create_pool。成功后 → 记录日志 [OutdoorIQ] Running in Postgres mode。
2. 如果连接池创建失败（超时、凭据错误、数据库宕机）或未设置 DATABASE_URL，服务会使用 100 多个真实湖泊的数据初始化内存中的 SQLite 数据库，并记录日志 [OutdoorIQ] Running in SQLite fallback mode。

无论 Postgres 是否可用，服务始终都会启动。

功能	Postgres 模式	SQLite 回退模式
湖泊目录	72,669 个（12 个州）	约 106 个（WI、MN、IL、IA、MO）
放养事件	293,821 条历史记录	约 150 条模板化事件，按近期程度调整
物种覆盖范围	CastIQ 中所有州和物种	精选子集（walleye、bass、musky、trout、crappie、perch、pike、panfish、salmon、lake_trout、sauger、white_bass、sturgeon、catfish、bluegill、smallmouth_bass）
年度同比分析	支持 — 多年放养记录	有限 — 事件以“当前时间”为基准
放养计划工具	真实历史规律	根据种子数据估算
天气、评分、报告	相同	相同

---

本地开发

git clone <this repo>
cd mcp-outdoors
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Run with SQLite fallback (no DATABASE_URL needed)
python -m run

# OR run against the CastIQ Postgres
export DATABASE_URL=postgresql://vikinetic:vikinetic_dev@localhost:5444/vikinetic
python -m run

然后：

curl -s http://localhost:8080/health
curl -s -X POST http://localhost:8080/mcp \
  -H "X-API-Key: outdooriq-dev-key-001" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

测试

pytest -v

测试套件涵盖 SQLite 回退路径和 Postgres 分发路径（通过模拟的 asyncpg 连接池），还涵盖身份验证、速率限制、全部 10 个工具、JSON-RPC 初始化 / 列表 / 调用，以及评分算法的分档计算。

---

部署到 Railway

仓库根目录中包含一个 deploy.sh 脚本。在 Mac 上运行（Cowork 沙盒无法访问 Railway/Stripe/Cloudflare API）：

./deploy.sh

该脚本需要 RAILWAY_API_TOKEN（或将 RAILWAY_TOKEN 导出为 RAILWAY_API_TOKEN），将项目指向 nixpacks.toml，并在你也已在 Railway 上配置 CastIQ Postgres 的情况下设置 DATABASE_URL 环境变量。

Railway 注意事项（已处理）： Railway exec 的 startCommand 不通过 shell 运行，因此 $PORT 不会展开。我们使用 python -m run，并在 run.py 中通过 os.environ 读取 PORT。

---

MCPize 列表文案

OutdoorIQ MCP — 户外休闲 AI Agent 的数据层。 72,000 多个美国湖泊、 293,000 多条鱼类放养事件，以及实时天气，汇集于一个经过身份验证的端点。 按名称、州或面积搜索湖泊；按物种和月份筛选放养历史；计算 0-100 的 钓鱼适宜度评分，综合考虑近期程度、物种多样性、湖泊面积和当前状况。一次 JSON-RPC 调用即可取代多源 ETL。

专为钓鱼应用、行程规划助手、旅行礼宾服务和户外品牌 Agent 打造。Pro 版 每月 $14，可无限使用；也可按每次调用 $0.01 付费。免费开发者套餐（每天 50 次调用）让你在付费前即可发布原型。使用 claude mcp add outdooriq-mcp --url https://mcp.castiq.net/mcp 安装。

---

许可证

MIT。请参阅 LICENSE。