内容
# 股票图片服务器
<!-- mcp-name: io.github.Hasilt/images-mcp -->
一个MCP服务器，允许克劳德代码（或任何MCP兼容代理）通过工具调用搜索和下载股票图片 — 在撰写SEO博客帖子或其他内容时，用于获取图片的来源非常有用。
## 提供商
| 提供商 | API类型 | 需要密钥 | 默认速率限制 |
| --------------- | --------------------- | ------------ | ------------------------------------------------- |
| Unsplash | 官方 | 是 | 50/小时演示，5000/小时生产 |
| Pexels | 官方 | 是 | 200/小时 |
| Pixabay | 官方 | 是 | 100请求/60秒 |
| Freepik | 官方 | 是 | 可配置（取决于计划） |
| StockVault | 官方 | 是 | 可配置（未记录，保守的默认值） |
| Burst (Shopify) | **非官方爬虫** | 否 | 自行实施，礼貌的默认 |
Burst 没有公共API。它被包含为一个尽力而为的HTML爬虫，清楚地标记为不支持 - 任何故障都会被捕获并报告为空结果，而不是破坏`search_all_images`。
## 安装
每个用户都在本地运行服务器，并提供自己的提供商API密钥 — 没有共享托管或中心化密钥。
与[克劳德代码](https://docs.claude.com/en/docs/claude-code):
```bash
claude mcp add stock-image-mcp \
-e UNSPLASH_ACCESS_KEY=... \
-e UNSPLASH_TIER=demo \
-e PEXELS_API_KEY=... \
-e PIXABAY_API_KEY=... \
-e FREEPIK_API_KEY=... \
-e FREEPIK_REQUESTS_PER_MINUTE=60 \
-e STOCKVAULT_API_KEY=... \
-e STOCKVAULT_REQUESTS_PER_HOUR=60 \
-e BURST_REQUESTS_PER_MINUTE=10 \
-e DEFAULT_PROVIDER=pexels \
-e DOWNLOAD_DIR=./downloads \
-- uvx stock-image-mcp
```
与[OpenAI Codex CLI](https://github.com/openai/codex):
```bash
codex mcp add stock-image-mcp \
--env UNSPLASH_ACCESS_KEY=... \
--env UNSPLASH_TIER=demo \
--env PEXELS_API_KEY=... \
--env PIXABAY_API_KEY=... \
--env FREEPIK_API_KEY=... \
--env FREEPIK_REQUESTS_PER_MINUTE=60 \
--env STOCKVAULT_API_KEY=... \
--env STOCKVAULT_REQUESTS_PER_HOUR=60 \
--env BURST_REQUESTS_PER_MINUTE=10 \
--env DEFAULT_PROVIDER=pexels \
--env DOWNLOAD_DIR=./downloads \
-- uvx stock-image-mcp
```
与[Gemini CLI](https://github.com/google-gemini/gemini-cli):
```bash
gemini mcp add stock-image-mcp \
-e UNSPLASH_ACCESS_KEY=... \
-e UNSPLASH_TIER=demo \
-e PEXELS_API_KEY=... \
-e PIXABAY_API_KEY=... \
-e FREEPIK_API_KEY=... \
-e FREEPIK_REQUESTS_PER_MINUTE=60 \
-e STOCKVAULT_API_KEY=... \
-e STOCKVAULT_REQUESTS_PER_HOUR=60 \
-e BURST_REQUESTS_PER_MINUTE=10 \
-e DEFAULT_PROVIDER=pexels \
-e DOWNLOAD_DIR=./downloads \
-- uvx stock-image-mcp
```
或使用[`uvx`](https://docs.astral.sh/uv/guides/tools/)手动将其添加到您的MCP配置中（无需克隆或安装步骤 — `uvx`会在首次运行时从PyPI获取包）：
```json
{
"mcpServers": {
"stock-image-mcp": {
"command": "uvx",
"args": ["stock-image-mcp"],
"env": {
"UNSPLASH_ACCESS_KEY": "...",
"UNSPLASH_TIER": "demo",
"PEXELS_API_KEY": "...",
"PIXABAY_API_KEY": "...",
"FREEPIK_API_KEY": "...",
"FREEPIK_REQUESTS_PER_MINUTE": "60",
"STOCKVAULT_API_KEY": "...",
"STOCKVAULT_REQUESTS_PER_HOUR": "60",
"BURST_REQUESTS_PER_MINUTE": "10",
"DEFAULT_PROVIDER": "pexels",
"DOWNLOAD_DIR": "./downloads"
}
}
}
}
```
只有`UNSPLASH_ACCESS_KEY`、`PEXELS_API_KEY`、`PIXABAY_API_KEY`、`FREEPIK_API_KEY`和`STOCKVAULT_API_KEY`是实际的密钥 — 仅设置您要启用的提供商的密钥，其余的密钥可以省略；任何未提供的提供商密钥都将被`search_all_images`跳过，并在直接通过`search_stock_images`查询时被拒绝。剩余的变量是可选的调优旋钮，如上所示具有默认值 — 请参阅`.env.example`以获取完整的列表。
## 工具
- `search_stock_images(query, provider="default", orientation=None, per_page=10, page=1)`
- `search_all_images(query, orientation=None, per_page=5)` — 同时查询所有已配置的提供商
- `get_best_image(query, provider="default")`
- `download_image(url, dest_path, provider=None)` — 保存本地，返回图片来源文本（如果图片来自之前的搜索）
- `get_attribution(provider, image_id)`
- `get_rate_limit_status(provider=None)`
## 用法
您不需要直接调用这些工具 — 您只需与您的代理对话，它会根据您的请求和上述工具描述决定何时调用它们。 有几件事情需要注意：
- 只需用普通英语询问即可。 “为博客帖子找3张山脉的风景照片”足以触发`search_all_images`（或`search_stock_images`，如果您指定提供商）。 “将Unsplash的第一个结果下载到`./images/hero.jpg`"会触发`download_image`。 “这个小时我还剩多少个Pexels请求？”会触发`get_rate_limit_status`。
- `search_stock_images`需要特定的提供商（或`"default"`）；`search_all_images`只会查询您已配置的提供商密钥并合并结果。 如果您关心使用哪个提供商，请说“仅搜索Pexels”或类似的话。
- 几个提供商（特别是Unsplash和Pexels）如果您在公共场合实际使用图片，则需要注明出处。 `download_image`会在适用时返回出处文本以及文件 — 需要您自行复制到图片的任何位置，服务器不会为您执行此操作。
- 如果您想手动调用工具而不是通过对话，请参见下面的开发部分中的MCP检查器。
## 本地开发
从克隆版开始而不是从已发布的包：
```bash
uv sync
cp .env.example .env # 填写您要启用的提供商的API密钥
uv run stock-image-mcp
```
将您的克劳德配置指向本地检查点而不是`uvx`:
```json
{
"mcpServers": {
"stock-image-mcp": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/stock-image-mcp",
"run",
"stock-image-mcp"
],
"env": {
"UNSPLASH_ACCESS_KEY": "...",
"UNSPLASH_TIER": "demo",
"PEXELS_API_KEY": "...",
"PIXABAY_API_KEY": "...",
"FREEPIK_API_KEY": "...",
"FREEPIK_REQUESTS_PER_MINUTE": "60",
"STOCKVAULT_API_KEY": "...",
"STOCKVAULT_REQUESTS_PER_HOUR": "60",
"BURST_REQUESTS_PER_MINUTE": "10",
"DEFAULT_PROVIDER": "pexels",
"DOWNLOAD_DIR": "./downloads"
}
}
}
}
```
## 开发
```bash
uv run pytest # 测试套件（模拟HTTP，无需实时密钥）
uv run ruff check . # 检查代码规范
uv run ruff format . # 格式化代码
uv run mypy src # 类型检查
```
要针对真实提供商进行测试，请使用[MCP检查器](https://modelcontextprotocol.io/docs/tools/inspector):
```bash
npx @modelcontextprotocol/inspector uv run stock-image-mcp
```
