demo-mcp-server
This is a Python-based MCP (Model Context Protocol) server providing utility tools for testing connectivity, system inspection, file operations, arithmetic, and time retrieval.
Echo: Reflects back any input text — useful for testing server connectivity.
System Info: Returns OS and Python interpreter details.
Read Text File: Reads a local text file by path, with a configurable byte limit (default 64KB) to avoid overloading the LLM.
Add: Computes the sum of two numbers.
Calculate: Safely evaluates simple arithmetic expressions (e.g.,
1 + 2 * (3 - 4)), supporting+ - * / ( ) . %without allowing variables or function calls.Get Current Time: Returns the current time in ISO-8601 format, with optional IANA timezone support (e.g.,
UTC,America/New_York).
The server also supports MCP Resources (e.g., a greeting resource), MCP Prompts (e.g., a summarize prompt), on-demand Python dependency installation, and tools for finding C identifier definitions and declarations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@demo-mcp-server what time is it in Tokyo?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
demo-mcp-server
一个使用 Python 编写的 Model Context Protocol (MCP) Server, 可直接接入 Cline / Claude Desktop 等 MCP 客户端。
设计要点
始终在虚拟环境中运行:
run.sh自动创建.venv、安装依赖,Cline 配置只需一行command。主框架与能力解耦:
server.py只负责启动与装配;所有业务工具 / 资源 / 提示位于tools/包内,新增能力无需改动任何现有文件。能力自注册:每个能力子包通过
__register__.py自我注册,无需手动维护模块清单。按需依赖:每个能力子包维护自己的
requirements.txt,不使用的模块无需安装其依赖。
Related MCP server: Remote MCP Server
环境要求
Python 3.10+
Linux / macOS(
run.sh为 Bash 脚本;Windows 见下方说明)
快速开始
方式一:run.sh(推荐)
git clone git@github.com:ZureJack/demo-mcp-server.git
cd demo-mcp-server
./run.sh首次运行自动创建 .venv/ 并安装核心依赖;再次启动直接进入 server。
方式二:pip install
pip install .
demo-mcp-server # 启动 server安装后可以直接在任意目录通过 demo-mcp-server 命令启动(无需 run.sh)。
可视化调试
source .venv/bin/activate
mcp dev server.py内置能力
模块 | 说明 | 文档 |
| 回显、系统信息 | |
| 算术运算 | |
| 当前时间(支持时区) | |
| 读取文本文件 | |
| MCP Resources(greeting) | |
| MCP Prompts(summarize) | |
| 按需安装模块依赖 | |
| 查找 C 标识符定义与声明 |
在 Cline 中接入
在 cline_mcp_settings.json 中加入:
{
"mcpServers": {
"demo-mcp-server": {
"command": "/home/loto/work/mcp/run.sh"
}
}
}配置文件位置:
VS Code (Linux):
~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.jsonVS Code (macOS):
~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.jsonVS Code (Windows):
%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Windows 用户
通过 WSL 调用:
{
"mcpServers": {
"demo-mcp-server": {
"command": "wsl",
"args": ["/home/loto/work/mcp/run.sh"]
}
}
}添加新能力
得益于"主框架/能力"分离的设计,新增能力只需在 tools/ 下新建一个子包,
无需修改任何现有文件。
子包结构
一个能力子包由 3 个文件组成:
tools/weather/ # 子包目录名即为能力名
├── __init__.py # 能力实现:注册工具/资源/提示
├── __register__.py # 自注册入口(一行代码)
└── requirements.txt # (可选)本模块的外部依赖各文件说明
__init__.py
能力实现文件。必须暴露一个 register(mcp) 函数,在此函数内通过装饰器注册工具/资源/提示。
"""天气查询能力。""" # 模块文档字符串
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from mcp.server.fastmcp import FastMCP
def register(mcp: "FastMCP") -> None:
@mcp.tool()
def fetch_weather(city: str) -> dict:
"""根据城市名查询天气。"""
# ... 你的实现 ...
return {"city": city, "temp": 25}约定:
不要在模块顶层引用全局
mcp,保证模块与主框架解耦,便于独立导入和单元测试。可以同时注册多个 tool/resource/prompt。
工具的参数类型注解会被 MCP SDK 自动转为 JSON Schema,客户端(如 Cline)会据此生成参数填写界面。
__register__.py
自注册入口。register_all() 会通过子进程执行此文件,将模块名写入 .registry.json。
from lib.registry import register_module
register_module("weather")仅此两行,不可省略。这个步骤让主框架知道存在这个能力模块。
requirements.txt(可选)
该模块的外部 Python 依赖,每行一个包名(标准 pip 格式):
requests>=2.31.0
beautifulsoup4>=4.12.0如果模块只使用 Python 标准库,此文件可以留空(或写注释说明无依赖)。
安装方式:
python tools/install_deps/install-deps.py # 安装所有模块的依赖
python tools/install_deps/install-deps.py weather # 只安装指定模块的依赖AI agent 也可以直接调用 install_deps_for_modules 工具在线安装。
注册与生效
保存文件后,Cline 会自动发现变更并重启 MCP server。重启后即可看到新的工具——server.py 和 tools/__init__.py 都不需要修改。
如果想手动刷新注册信息(一般情况下不需要),可以在项目根目录执行:
PYTHONPATH=. python -c "
import tools
from mcp.server.fastmcp import FastMCP
mcp = FastMCP('test')
tools.register_all(mcp)
print('已注册模块:', tools.TOOL_MODULES)
"常见问题
Q1. ./run.sh: Permission denied
chmod +x run.shQ2. ModuleNotFoundError: No module named 'mcp'
删除 .venv 重新运行 ./run.sh 即可。
Q3. server 启动后没有任何输出 正常行为:stdio 传输下 stdout 只用于 JSON-RPC,日志在 stderr。
Q4. 想强制使用别的 Python 版本创建 venv
PYTHON_BIN=/usr/bin/python3.12 ./run.sh参考
Available Tools
6 toolsaddA
计算两个数之和。
Inputs: a (required), b (required). Returns: result
calculateA
对一个简单的算术表达式求值。
仅允许数字、空白以及 + - * / ( ) . % 运算符,
禁止任何变量、函数或属性访问,以避免代码注入。
Args:
expression: 例如 "1 + 2 * (3 - 4)"。
Returns: 表达式的字符串化结果。
Inputs: expression (required). Returns: result
echoA
回显输入文本,可用于测试 server 是否连通。
Args: text: 要回显的文本。
Returns: 与输入完全一致的字符串。
Inputs: text (required). Returns: result
get_current_timeA
获取当前时间。
Args: tz: 可选 IANA 时区名(例如 "Asia/Shanghai", "UTC", "America/New_York")。未提供时使用系统本地时区。
Returns: ISO-8601 格式的时间字符串。
Inputs: tz. Returns: result
read_text_fileA
读取一个本地文本文件的内容。
Args: path: 文件的绝对路径或相对于 server 启动目录的相对路径。 max_bytes: 最多读取的字节数,防止把超大文件喂给 LLM,默认 64KB。
Returns: 文件文本内容(UTF-8 解码,非法字节会被替换)。
Inputs: path (required), max_bytes. Returns: result
system_infoA
返回当前运行 server 的系统与解释器信息。
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Most tools have distinctly different purposes, but add and calculate both perform arithmetic, which could cause confusion. Descriptions help differentiate (add handles two numbers, calculate evaluates expressions), but the overlap is notable.
Tool names use lowercase with underscores for multi-word names, but the pattern is inconsistent: add, calculate, and echo are single verbs, while get_current_time and read_text_file follow verb_noun. This lack of uniformity reduces predictability.
With 6 tools, the server is well-scoped for a demo utility set. Each tool serves a clear role without being overwhelming or too sparse.
The tools cover common utility tasks like arithmetic, echoing, time retrieval, file reading, and system info. While it lacks some common utilities (e.g., string manipulation, random generation), it is adequate for a demo server with only minor gaps.
Maintenance
Related MCP Connectors
A simple MCP server built with FastMCP and python
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Read-only developer, date, finance, and text utilities. Authless remote MCP server by Clean.tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Python-based MCP server demonstrating basic math and text tools, supporting both SSE and STDIO transports for integration with AI assistants like Cline in VS Code.-
- FlicenseNot gradedqualityCmaintenanceA Python-based MCP server that provides mathematical tools like addition and random number generation, plus server metadata.-
- FlicenseNot gradedqualityDmaintenanceA minimal MCP server providing basic tools for arithmetic, text echoing, and timezone-aware current time retrieval.-
- FlicenseNot gradedqualityDmaintenanceA simple MCP server that provides basic utility tools for text manipulation, file operations, and calculations, intended to be connected to Claude AI desktop app.-