内容
# 基本MCP工具
一个小型、自行托管的 [MCP](https://modelcontextprotocol.io)（模型上下文协议）服务器，为您的LLM提供几个基本工具：私有网络搜索、网页抓取和当前日期/时间。它通过Docker Compose自带一个SearXNG实例，因此搜索保持本地化，不需要任何API密钥。
## 工具
| 工具 | 描述 |
| --- | --- |
| `search` | 通过捆绑的SearXNG实例搜索网络。返回标题、网址和摘要。 |
| `fetch_page` | 获取网址并返回其清理后的可读文本（脚本、导航、页脚等已被剥离）。 |
| `get_date` | 获取当前日期（`YYYY-MM-DD`）。 |
| `get_time` | 获取当前本地时间，带时区。 |
## 快速开始（Docker Compose）
需要带有Compose插件的Docker。
```sh
git clone https://github.com/Tyguy047/Basic-MCP-Tools.git
cd Basic-MCP-Tools
docker compose up -d --build
```
这将启动两个容器：
- **searxng** — 搜索后端。它仅在Compose网络内部可达（不发布到您的主机）。
- **basic-mcp-tools** — MCP服务器，通过可流式HTTP传输监听 **端口8080**。
MCP端点是：
```
http://localhost:8080/mcp
```
### 连接客户端
任何支持可流式HTTP的MCP客户端都可以使用。例如，使用Claude Code：
```sh
claude mcp add --transport http basic-tools http://localhost:8080/mcp
```
或在基于JSON的客户端配置中：
```json
{
"mcpServers": {
"basic-tools": {
"type": "http",
"url": "http://localhost:8080/mcp"
}
}
}
```
## 配置
- **时区** — `get_date`/`get_time` 使用容器的时区。在 `docker-compose.yml` 中设置 `TZ`（默认为 `America/New_York`）。
- **SearXNG** — 设置位于 `searxng/settings.yml`。`search` 工具的一个要求是 `json` 输出格式保持启用。容器在每次启动时生成一个随机的 `SEARXNG_SECRET`。
- **搜索后端位置** — MCP服务器通过环境变量 `SEARXNG_IP` 和 `SEARXNG_PORT`（在 `docker-compose.yml` 中设置）找到SearXNG。
## 在没有Docker的情况下运行
如果您指向现有的SearXNG实例（启用了 `json` 格式），可以直接运行服务器：
```sh
pip install -r requirements.txt
export SEARXNG_IP=<searxng-host>
export SEARXNG_PORT=<searxng-port>
python main.py
```
服务器监听 `0.0.0.0:8080`。Docker镜像中使用Python 3.14；其他近期版本也应该可以使用。
## 项目布局
```
main.py # FastMCP服务器；注册工具
functions/
searxng.py # search — 查询SearXNG的JSON API
fetch.py # fetch_page — httpx + BeautifulSoup文本提取
date.py # get_date
time.py # get_time
searxng/settings.yml # SearXNG配置（启用JSON输出）
docker-compose.yml # searxng + mcp-tools服务
Dockerfile # Python 3.14精简镜像，用于MCP服务器
```
## 注意事项
- 服务器未经身份验证，旨在本地或受信任的网络环境中使用。不要将8080端口暴露到公网。
- 添加新工具分为两步：在 `functions/` 中编写一个函数（其文档字符串成为工具描述），并在 `main.py` 中使用 `mcp.tool()(your_function)` 注册它。
