Content
# PhpMCP
**A High-Quality MCP Server Collection in Pure PHP**
**PhpMCP** is a comprehensive suite of 10 production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers built entirely in PHP 8.5 with **zero external dependencies**. Each server implements the MCP specification (2025-11-25) over STDIO transport, providing Tools, Resources, and Prompts that AI agents (Claude, ChatGPT, Cursor, etc.) can discover and invoke at runtime.
---
## ✨ Key Features
| Feature | Count |
|---|---|
| **Servers** | 10 |
| **Tools** (callable functions) | 98 |
| **Resources** (readable data) | 20 |
| **Prompts** (templates) | 14 |
| **Zero Dependencies** | ✓ — Pure PHP, no Composer needed |
| **Protocol** | MCP 2025-11-25 (JSON-RPC 2.0) |
| **Transport** | STDIO |
| **PHP Version** | 8.5+ |
| **License** | MIT |
### Server List
| # | Server | Tools | Resources | Prompts | Description |
|---|--------|-------|-----------|---------|-------------|
| 1 | **Weather** | 4 | 2 | 2 | City weather, forecasts, comparison (15 cities) |
| 2 | **Calculator** | 14 | 2 | 1 | Math: add, subtract, multiply, divide, power, sqrt, trig, log, factorial, GCD, LCM |
| 3 | **FileSystem** | 11 | 1 | 1 | File read/write/copy/move/delete, directory listing, search |
| 4 | **DateTime** | 10 | 2 | 2 | Current time, timezone conversion, date diff, formatting, week number |
| 5 | **Text Processing** | 15 | 1 | 1 | Case conversion, regex, encode/decode, split/join, trim, wrap |
| 6 | **Database** | 8 | 3 | 1 | SQLite demo DB, SELECT queries, employee stats, project summary |
| 7 | **WebTool** | 8 | 2 | 1 | URL fetch, website status, metadata extraction, URL validation, QR code |
| 8 | **SystemInfo** | 10 | 2 | 1 | OS, PHP config, memory, disk, environment, process info |
| 9 | **Code Assistant** | 10 | 2 | 2 | Syntax validation, line counting, function extraction, docblock generation, UUID |
| 10 | **Translation** | 8 | 3 | 2 | Multi-language translate, phrase lookup, transliteration, language detection |
---
## 🚀 Quick Start
### Prerequisites
- PHP 8.5 or later
- Extensions: `json`, `mbstring`, `pcre` (typically enabled by default)
- For **Database** server: `sqlite3`, `pdo_sqlite`
- For **WebTool** server: `curl`, `dom`, `xml`
### Run a Server
Pick any server and pipe JSON-RPC messages through STDIO:
```bash
# Windows
php servers\weather.php
# Linux / macOS
php servers/weather.php
```
Or use the launcher:
```bash
run_server.bat weather
```
### Connect from an MCP Client
Add the server to your MCP client configuration (e.g., Claude Desktop, Cursor, or any MCP host):
```json
{
"mcpServers": {
"php-calculator": {
"command": "php",
"args": ["C:/path/to/servers/calculator.php"]
},
"php-weather": {
"command": "php",
"args": ["C:/path/to/servers/weather.php"]
}
}
}
```
### Test Locally
```bash
# Protocol-level test (init, tools, resources, prompts)
php test_server.php servers/calculator.php all
# Tool functionality test
php test_tools.php servers/calculator.php
```
---
## 📦 Architecture
### Framework
All servers extend a shared base class `framework/McpServer.php` which provides:
- **JSON-RPC 2.0** message parsing and response formatting
- **MCP Lifecycle**: `initialize` → `notifications/initialized` → operation
- **Method routing**: `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get`, `ping`
- **Error handling**: Standard JSON-RPC error codes with descriptive messages
- **Notification support**: Server-initiated events
### Protocol Flow
```
Client Server
│ │
├─ initialize ─────────────────>│
│<─ protocolVersion, capabilities│
│ │
├─ notifications/initialized ───>│
│ │
├─ tools/list ─────────────────>│
│<─ tool definitions ───────────│
│ │
├─ tools/call {name, args} ────>│
│<─ result {content} ──────────│
│ │
├─ resources/list ─────────────>│
│<─ resource list ─────────────│
│ │
├─ prompts/list ───────────────>│
│<─ prompt list ───────────────│
```
### Adding a New Server
```php
<?php
require_once __DIR__ . '/../framework/McpServer.php';
use Mcp\McpServer;
class MyServer extends McpServer
{
protected function getServerInfo(): array
{
return ['name' => 'My Server', 'version' => '1.0.0'];
}
protected function getTools(): array
{
return [
[
'name' => 'hello',
'description' => 'Say hello',
'inputSchema' => [
'type' => 'object',
'properties' => [
'name' => ['type' => 'string', 'description' => 'Your name'],
],
'required' => ['name'],
],
],
];
}
protected function callTool(string $name, array $arguments): array
{
return [
'content' => [['type' => 'text', 'text' => "Hello, {$arguments['name']}!"]],
];
}
}
$server = new MyServer();
$server->run();
```
---
## 📖 Server Details
### 1. Weather Server
Provides current weather, forecasts, and city comparisons.
**Tools:**
- `get_weather` — Current conditions for any city (15 supported)
- `get_forecast` — 1–7 day forecast
- `list_cities` — All available cities
- `compare_weather` — Side-by-side comparison of two cities
### 2. Calculator Server
A full-featured math tool with 14 operations.
**Tools:** `add`, `subtract`, `multiply`, `divide`, `power`, `sqrt`, `modulo`, `percentage`, `average`, `factorial`, `gcd`, `lcm`, `trigonometry` (sin/cos/tan/asin/acos/atan), `logarithm` (ln/log10)
### 3. FileSystem Server
Safe file operations within the allowed directory.
**Tools:** `read_file`, `write_file`, `list_directory`, `create_directory`, `delete_file`, `delete_directory`, `copy_file`, `move_file`, `get_file_info`, `search_files`, `read_file_lines`
### 4. DateTime Server
Timezone-aware date/time utilities.
**Tools:** `get_current_time`, `convert_timezone`, `date_difference`, `format_date`, `add_duration`, `get_unix_timestamp`, `list_timezones`, `get_week_number`, `is_leap_year`, `get_day_of_year`
### 5. Text Processing Server
15 text manipulation tools.
**Tools:** `case_convert`, `count_text`, `regex_match`, `regex_replace`, `encode_decode`, `split_text`, `join_text`, `trim_text`, `pad_text`, `reverse_text`, `substring`, `find_replace`, `word_wrap`, `shuffle_text`, `extract_urls`
### 6. Database Server
A demo SQLite database with employees, departments, and projects.
**Tools:** `query` (SELECT only, safe), `list_tables`, `describe_table`, `get_employee_stats`, `get_project_summary`, `search_employee`, `insert_employee`, `get_schema`
### 7. WebTool Server
Fetch and analyze web content.
**Tools:** `fetch_url`, `search_web`, `check_website_status`, `extract_metadata`, `shorten_url`, `http_headers`, `validate_url`, `generate_qrcode`
### 8. SystemInfo Server
Comprehensive system diagnostic tools.
**Tools:** `get_os_info`, `get_php_info`, `get_memory_info`, `get_disk_info`, `get_environment`, `get_load_average`, `get_network_info`, `get_process_info`, `get_uptime`, `get_composer_info`
### 9. Code Assistant Server
Code analysis and generation tools for developers.
**Tools:** `format_code`, `validate_syntax`, `count_lines`, `extract_functions`, `generate_docblock`, `minify_code`, `convert_case`, `generate_uuid`, `estimate_complexity`, `find_todos`
### 10. Translation Server
Multi-language translation with a built-in phrase book (20+ languages).
**Tools:** `translate`, `list_languages`, `detect_language`, `lookup_phrase`, `get_language_name`, `transliterate`, `word_count`, `language_comparison`
---
## 🧪 Testing
```bash
# Test all protocol aspects
php test_server.php servers/calculator.php all
# Test specific area
php test_server.php servers/weather.php tools
# Test tool functionality with real arguments
php test_tools.php servers/database.php
```
---
## 🔧 Configuration
No configuration files needed. All servers are self-contained.
### Windows: Enable Required Extensions
Edit your `php.ini` and enable:
```ini
extension=curl
extension=fileinfo
extension=mbstring
extension=openssl
extension=pdo_sqlite
extension=sqlite3
extension=dom
extension=xml
```
---
## 📄 License
This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.
---
## 🌐 Resources
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP Specification](https://spec.modelcontextprotocol.io)
- [MCP PHP SDK (official)](https://github.com/modelcontextprotocol/php-sdk)
- [JSON-RPC 2.0](https://www.jsonrpc.org/specification)
---
<br>
<h1 align="center">PhpMCP</h1>
<p align="center"><strong>纯 PHP 编写的高质量 MCP 服务器合集</strong></p>
<p align="center">
<strong>PhpMCP</strong> 是一套完整的、生产就绪的 <a href="https://modelcontextprotocol.io">Model Context Protocol (MCP)</a> 服务器集，
全部使用 PHP 8.5 原生编写，<strong>零外部依赖</strong>。
</p>
<p align="center">
每台服务器实现了 MCP 2025-11-25 协议规范，通过 STDIO 传输层提供工具（Tools）、资源（Resources）和提示模板（Prompts），
供 Claude、ChatGPT、Cursor 等 AI 代理在运行时动态发现和调用。
</p>
---
## ✨ 核心特性
| 指标 | 数值 |
|------|------|
| **服务器数量** | 10 |
| **工具（可调用函数）** | 98 |
| **资源（可读数据）** | 20 |
| **提示模板** | 14 |
| **零依赖** | ✓ — 纯 PHP，无需 Composer |
| **协议版本** | MCP 2025-11-25 (JSON-RPC 2.0) |
| **传输方式** | STDIO |
| **PHP 版本** | 8.5+ |
| **开源协议** | MIT |
### 服务器列表
| # | 服务器 | 工具数 | 资源数 | 提示数 | 说明 |
|---|--------|--------|--------|--------|------|
| 1 | **Weather** | 4 | 2 | 2 | 城市天气查询、预报、对比（15个城市） |
| 2 | **Calculator** | 14 | 2 | 1 | 14种数学运算：加减乘除、幂、根号、三角、对数、阶乘、GCD、LCM |
| 3 | **FileSystem** | 11 | 1 | 1 | 文件读/写/复制/移动/删除，目录遍历，搜索 |
| 4 | **DateTime** | 10 | 2 | 2 | 时间获取、时区转换、日期差、格式化、周数 |
| 5 | **Text Processing** | 15 | 1 | 1 | 大小写转换、正则、编解码、拆分/合并、修剪、换行 |
| 6 | **Database** | 8 | 3 | 1 | SQLite 演示数据库，SELECT 查询，员工统计，项目汇总 |
| 7 | **WebTool** | 8 | 2 | 1 | URL 抓取、网站状态、元数据提取、URL 验证、二维码 |
| 8 | **SystemInfo** | 10 | 2 | 1 | OS、PHP 配置、内存、磁盘、环境变量、进程信息 |
| 9 | **Code Assistant** | 10 | 2 | 2 | 语法验证、代码行统计、函数提取、文档块生成、UUID |
| 10 | **Translation** | 8 | 3 | 2 | 多语种翻译、短语查询、音译、语言检测（20+语种） |
---
## 🚀 快速开始
### 环境要求
- PHP 8.5 或更高版本
- 扩展：`json`、`mbstring`、`pcre`（通常默认已启用）
- **Database** 服务器需要：`sqlite3`、`pdo_sqlite`
- **WebTool** 服务器需要：`curl`、`dom`、`xml`
### 启动服务器
通过 STDIO 管道发送 JSON-RPC 消息：
```bash
# Windows
php servers\weather.php
# Linux / macOS
php servers/weather.php
```
或使用启动脚本：
```bash
run_server.bat weather
```
### 从 MCP 客户端连接
在客户端配置中添加服务器（例如 Claude Desktop、Cursor 等）：
```json
{
"mcpServers": {
"php-calculator": {
"command": "php",
"args": ["C:/path/to/servers/calculator.php"]
},
"php-weather": {
"command": "php",
"args": ["C:/path/to/servers/weather.php"]
}
}
}
```
### 本地测试
```bash
# 协议级测试（初始化、工具、资源、提示）
php test_server.php servers/calculator.php all
# 工具功能测试
php test_tools.php servers/calculator.php
```
---
## 📦 架构设计
### 框架层
所有服务器继承自共享基类 `framework/McpServer.php`，该基类提供：
- **JSON-RPC 2.0** 消息解析与响应格式化
- **MCP 生命周期**：`initialize` → `notifications/initialized` → 操作阶段
- **方法路由**：`tools/list`、`tools/call`、`resources/list`、`resources/read`、`prompts/list`、`prompts/get`、`ping`
- **错误处理**：标准 JSON-RPC 错误码及描述信息
- **通知机制**：服务器主动推送事件
### 协议流程
```
客户端 服务器
│ │
├─ initialize ─────────────────>│
│<─ 协议版本、能力声明 ──────────│
│ │
├─ notifications/initialized ───>│
│ │
├─ tools/list ─────────────────>│
│<─ 工具定义列表 ───────────────│
│ │
├─ tools/call {名称, 参数} ────>│
│<─ 执行结果 {content} ─────────│
│ │
├─ resources/list ─────────────>│
│<─ 资源列表 ──────────────────│
│ │
├─ prompts/list ───────────────>│
│<─ 提示模板列表 ──────────────│
```
### 新增一台服务器
```php
<?php
require_once __DIR__ . '/../framework/McpServer.php';
use Mcp\McpServer;
class MyServer extends McpServer
{
protected function getServerInfo(): array
{
return ['name' => 'My Server', 'version' => '1.0.0'];
}
protected function getTools(): array
{
return [
[
'name' => 'hello',
'description' => 'Say hello',
'inputSchema' => [
'type' => 'object',
'properties' => [
'name' => ['type' => 'string', 'description' => 'Your name'],
],
'required' => ['name'],
],
],
];
}
protected function callTool(string $name, array $arguments): array
{
return [
'content' => [['type' => 'text', 'text' => "Hello, {$arguments['name']}!"]],
];
}
}
$server = new MyServer();
$server->run();
```
---
## 🧪 测试
```bash
# 测试所有协议方面
php test_server.php servers/calculator.php all
# 测试特定方面
php test_server.php servers/weather.php tools
# 使用真实参数测试工具功能
php test_tools.php servers/database.php
```
---
## 🔧 配置说明
无需配置文件，所有服务器开箱即用。
### Windows：启用所需扩展
编辑 `php.ini`，取消以下扩展的注释：
```ini
extension=curl
extension=fileinfo
extension=mbstring
extension=openssl
extension=pdo_sqlite
extension=sqlite3
extension=dom
extension=xml
```
---
## 📄 开源协议
本项目采用 **MIT 许可证** — 详见 [LICENSE](LICENSE) 文件。
---
## 🌐 相关资源
- [Model Context Protocol 官方网站](https://modelcontextprotocol.io)
- [MCP 协议规范](https://spec.modelcontextprotocol.io)
- [官方 MCP PHP SDK](https://github.com/modelcontextprotocol/php-sdk)
- [JSON-RPC 2.0 规范](https://www.jsonrpc.org/specification)
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available