Logo.dev MCP

Logo.dev MCP

通过 logo.dev API 查询公司 Logo 和品牌数据。

文档 | 配置向导 | PyPI | Docker

功能

• 获取 Logo（get_logo）— 根据域名、股票代码、ISIN、加密货币符号或品牌名称获取公司 Logo 图片及其 URL；支持尺寸、格式、主题、灰度、视网膜屏幕和回退选项。需要可发布密钥（pk_…）。
• 品牌搜索（search_brands）— 通过输入提示或精确匹配，将品牌或公司名称解析为候选域名和 Logo URL。需要密钥（sk_…）。
• 公司描述（describe_company）— 根据域名返回结构化的公司数据（名称、描述、品牌颜色、社交链接）。需要密钥（sk_…）。
• 完整品牌档案（get_brand）— 根据域名返回完整的品牌档案（Logo、品牌标志、横幅、颜色、描述），内容比 describe_company 更丰富。需要密钥（sk_…）。
• 优雅降级 — 仅在存在相应 API 密钥时才注册工具；缺少密钥的工具会对 MCP 客户端隐藏，而非注册后在调用时失败。

使用方法

在 MCP 客户端（Claude 等）中挂载此服务后，你可以：

• 获取 Logo — “获取 stripe.com 的 Logo。”使用 get_logo（需要可发布密钥）。
• 识别品牌域名 — “品牌‘Stripe’对应的域名是什么？”使用 search_brands（需要密钥）。
• 查询公司信息 — “Stripe 的品牌使用了哪些颜色？”使用 describe_company（需要密钥）。
• 获取完整品牌套件 — “显示 shopify.com 的完整品牌档案。”使用 get_brand（需要密钥）。
• 按股票代码获取 Logo — “获取 AAPL 的 Logo。”使用 get_logo 并设置 identifier_type=ticker（需要可发布密钥）。

安装

从 PyPI 安装

pip install logodev-mcp

如果你通过 pyproject.toml 中的 PROJECT-EXTRAS-START / PROJECT-EXTRAS-END 标记添加了可选扩展，请在下方记录：

从源代码安装

git clone https://github.com/pvliesdonk/logodev-mcp.git
cd logodev-mcp
uv sync --all-extras --all-groups

Docker

docker pull ghcr.io/pvliesdonk/logodev-mcp:latest

仓库根目录附带了一个 compose.yml，可作为起点 — 将 .env.example 复制为 .env，编辑后运行 docker compose up -d。

要连接远程 Python 调试器（仅用于开发 — 此协议未经身份验证），请参阅远程调试。

Linux 软件包（.deb / .rpm）

从 GitHub Releases 页面下载 .deb 或 .rpm 软件包。两者都会安装经过强化的 systemd 单元；环境配置从 /etc/logodev-mcp/env 读取（从随附的 /etc/logodev-mcp/env.example 复制）。

Claude Desktop（.mcpb bundle）

从 GitHub Releases 页面下载 .mcpb bundle，然后双击安装，或运行：

mcpb install logodev-mcp-<version>.mcpb

Claude Desktop 会通过 GUI 向导提示输入必需的环境变量——无需手动编辑 JSON。

有关 Claude Desktop 的手动配置和设置选项，请参阅 Claude Desktop 部署。

快速开始

logodev-mcp serve                                # stdio transport
logodev-mcp serve --transport http --port 8000   # streamable HTTP

如需以库的形式使用（嵌入领域逻辑而不使用 MCP 传输），请直接从 logodev_mcp 包导入——入口点请参阅项目在 src/logodev_mcp/ 下的领域模块。

服务信息

服务会注册一个内置的 get_server_info 工具（通过 fastmcp_pvl_core.register_server_info_tool），以便运维人员通过一次 MCP 调用确认已部署的版本。默认响应包含 server_name、server_version 和 core_version。与远程上游通信的服务，会在 src/logodev_mcp/server.py 的 DOMAIN-UPSTREAM-START / DOMAIN-UPSTREAM-END 哨兵标记之间接入上游版本报告——接入模式请参阅 CLAUDE.md。

配置

所有基于 fastmcp-pvl-core 的服务共用的核心环境变量：

变量	默认值	描述
FASTMCP_LOG_LEVEL	INFO	FastMCP 内部组件和应用日志记录器的日志级别（DEBUG / INFO / WARNING / ERROR）。-v CLI 标志会将级别覆盖为 DEBUG。
FASTMCP_ENABLE_RICH_LOGGING	true	设为 false 可输出纯文本 / 结构化 JSON 日志。
LOGODEV_MCP_KV_STORE_URL	file:///data/state	pvl-core 子系统的持久状态后端 URL——file:///path（重启后保留）、memory://（开发 / 临时使用）。

领域专用变量见下文的领域配置。

身份验证

调用方通过 bearer 令牌或 OIDC 进行身份验证（二者互斥）。有关设置、映射多主体令牌、OIDC 和故障排除，请参阅身份验证指南。

脚手架生成后的检查清单

运行 copier copy 和 gh repo create --push 后：

1. 填写本 README（Features、What you can do with it、Domain configuration、Key design decisions）及 CLAUDE.md 中的 DOMAIN 区块。
2. 配置 GitHub 密钥——见下文。
3. 安装开发和文档工具：uv sync --all-extras --all-groups。
4. 安装 pre-commit 钩子：uv run pre-commit install。
5. 在本地运行检查：uv run pytest -x -q && uv run ruff check --fix . && uv run ruff format . && uv run mypy src/ tests/。
6. 推送第一个提交——CI 应当通过。

GitHub 密钥

CI 工作流会引用三个仓库密钥。可通过 Settings → Secrets and variables → Actions 或使用 gh secret set 进行配置：

密钥	使用方	生成方式
RELEASE_TOKEN	release.yml、copier-update.yml	在 https://github.com/settings/personal-access-tokens/new 创建细粒度 PAT，并授予 contents: write 和 pull_requests: write 权限（copier-update 定时任务会创建 PR）。权限仅限此仓库。
CODECOV_TOKEN	ci.yml	前往 https://codecov.io，使用 GitHub 登录并添加仓库，然后从仓库设置页面复制上传令牌。
CLAUDE_CODE_OAUTH_TOKEN	claude.yml、claude-code-review.yml	在本地运行 claude setup-token，并粘贴生成的结果。

gh secret set RELEASE_TOKEN
gh secret set CODECOV_TOKEN
gh secret set CLAUDE_CODE_OAUTH_TOKEN

GITHUB_TOKEN 会自动提供——无需操作。

本地开发

PR 检查门禁（与 CI 一致）：

uv run pytest -x -q                                  # tests
uv run ruff check --fix . && uv run ruff format .    # lint + format
uv run mypy src/ tests/                              # type-check

pre-commit 会在每次提交时运行检查门禁的一部分；详情请参阅 .pre-commit-config.yaml，或查看 CLAUDE.md 中完整的 Hard PR Acceptance Gates。

故障排除

移动已搭建的项目

uv sync 会创建 .venv/bin/* 脚本，其 shebang 使用绝对路径，指向虚拟环境中的 Python。如果在搭建项目后移动仓库（mv /old/path /new/path），uv run pytest 会因过时的 shebang 指向与虚拟环境的 site-packages 不同的解释器而失败，并报错 ModuleNotFoundError: No module named 'fastmcp'。

修复方法：

rm -rf .venv
uv sync --all-extras --all-groups

也可以将 uv run python -m pytest 作为一次性解决方法（绕过过时的入口脚本封装）。

copier update 后刷新 uv.lock

当 copier update 引入新依赖时（例如在 pyproject.toml.jinja 中添加新的 extra），CI 会运行 uv sync --frozen，但因锁文件过时而失败。在本地运行 uv lock，并在接受 copier-update PR 时一并提交更新后的 uv.lock。

链接

• 文档
• llms.txt
• FastMCP
• fastmcp-pvl-core

域配置

域环境变量使用 LOGODEV_MCP_ 前缀：

变量	默认值	必需	描述
LOGODEV_MCP_PUBLISHABLE_KEY	—	有条件必需	logo.dev 公钥（pk_…）。启用 get_logo 工具。不设置则隐藏该工具。
LOGODEV_MCP_SECRET_KEY	—	有条件必需	logo.dev 密钥（sk_…）。启用 search_brands、describe_company 和 get_brand。不设置则隐藏这些工具。
LOGODEV_MCP_DETECT_PLAN	true	否	启动时探测 describe/brand 权限，并隐藏套餐不允许使用的工具。设为 false 可跳过探测，并注册所有密钥对应的工具。
LOGODEV_MCP_STATE_DIR	/data/state	否	存储套餐检测结果缓存（entitlements.json）的目录。

必须至少设置一个密钥，才能注册任何 API 工具。可以同时设置两个密钥，以启用全部四个工具。

logo.dev 各套餐可解锁的工具（免费套餐可用 get_logo/search_brands，任意付费套餐可用 describe_company，Pro/Enterprise 可用 get_brand）详见套餐与功能矩阵。

关键设计决策

• 双密钥门控 — LOGODEV_MCP_PUBLISHABLE_KEY 控制 get_logo；LOGODEV_MCP_SECRET_KEY 控制 search_brands、describe_company 和 get_brand。缺少对应密钥的工具不会注册，而不只是在调用时进行检查。
• 套餐检测会隐藏无权限的工具 — describe_company 需要付费套餐，get_brand 需要 Pro/Enterprise。logo.dev 没有套餐查询端点，因此服务会在启动时向 logo.dev 探测各工具的权限，并在收到 401/403 时禁用相应工具。search_brands 不受套餐限制；对于任何不明确的探测结果（超时、5xx、404、429），均默认放行并保持工具启用。检测结果会缓存在 LOGODEV_MCP_STATE_DIR 下，有效期为 7 天（轮换密钥后会重新探测）。设置 LOGODEV_MCP_DETECT_PLAN=false 可禁用此功能。
• 域逻辑不依赖 FastMCP — src/logodev_mcp/domain.py 包含 Service 类和 LogoDevError，不导入 FastMCP；src/logodev_mcp/tools.py 是唯一的 FastMCP 层。
• 错误以字符串形式呈现 — 域代码中引发的 LogoDevError 会在各工具包装器中捕获，并作为纯文本消息返回，这样 MCP 客户端看到的是易读的错误，而不是服务异常。
• Logo 工具返回 URL 和图像 — 除非设置 url_only=True，否则 get_logo 会同时返回 CDN URL（文本）和图像字节（图像内容块）；设置后则只返回 URL 字符串。