AI导哈

本地工具服务器

一个基于FastMCP构建的模型上下文协议(MCP)服务器，提供文件操作、文本处理、数学计算等多种实用工具，适合与Claude Desktop集成或部署为网络服务。

  • by pankajshakya627
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 pankajshakya627/File-MCP-server

使用说明

FastMCP本地Utils服务器

使用FastMCP构建的综合模型上下文协议（MCP）服务器，提供文件操作、文本处理、数学实用程序等。非常适合与Claude Desktop集成或作为网络服务部署。

🌟 特性

📁 文件操作

  • 读/写/追加 -完成文件操作
  • 智能文本替换 -查找并替换为发生计数
  • 安全删除 -通过验证删除文件
  • 覆盖保护 -防止意外覆盖的可选保护措施

📂 目录管理

  • 列出内容 -查看具有可选详细信息（大小、日期）的文件和目录
  • 查找文件 -使用glob模式的递归搜索
  • 创建目录 -使用父目录创建新目录
  • 智能组织 -按以下方式自动组织文件：
    • 类型：文件、图像、视频、音频、代码、档案等。
    • 日期：基于修改时间的年月文件夹
    • 尺寸：小型/中型/大型类别

📝 文本处理

  • 字计数器 -统计单词、字符和行数
  • 文本搜索 -查找带有上下文片段的文本
  • 统计 -详细的文本分析

🔢 数学运算

  • 计算器 -计算数学表达式（支持sqrt、sin、cos、log等）
  • 基础数学 -将数字与格式化输出相加和相乘

🛠️ 公用事业

  • 问候 -生成个性化消息
  • 时间/日期 -获取当前时间戳
  • 察看连接信息 -查询可用的工具和功能

📦 安装

先决条件

  • Python 3.10或更高版本
  • 紫外线 包管理器（推荐）

使用紫外线（推荐）

# Clone the repository
git clone https://github.com/pankajshakya627/File-MCP-server.git
cd File-MCP-server

# Install dependencies (uv will handle this automatically)
uv sync

# Run the server
uv run main.py

使用pip

# Clone the repository
git clone <your-repo-url>
cd mcp-local

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install fastmcp

# Run the server
python main.py

🚀 用法

STDIO传输（默认）

非常适合Claude Desktop和本地开发：

uv run main.py

发展模式

在代码更改时自动重新加载：

uv run fastmcp dev main.py

🔧 Claude桌面配置

将此添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "local-utils": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-local",
        "run",
        "main.py"
      ]
    }
  }
}

替换 /absolute/path/to/mcp-local 带有项目目录的实际路径。

更新配置后：

  1. 重新启动克劳德桌面
  2. 寻找🔌 图标确认服务器已连接
  3. 开始在对话中使用这些工具！

📚 可用工具

文件操作

read_file(path: str) -> str

读取并返回包含元数据的文件内容。

# Example usage in Claude
"Read the file at ~/Documents/notes.txt"

write_file(path: str, content: str, overwrite: bool = True) -> str

将内容写入文件。如果需要，创建父目录。

"Write 'Hello World' to ~/test.txt"
"Write the content to config.json without overwriting if it exists"

append_to_file(path: str, content: str) -> str

将内容附加到文件末尾。

"Append today's log entry to ~/logs/app.log"

update_file(path: str, old_text: str, new_text: str, count: int = -1) -> str

用出现计数替换文件中的文本。

"Replace 'TODO' with 'DONE' in ~/project/tasks.md"
"Replace the first occurrence of 'debug = True' with 'debug = False'"

delete_file(path: str) -> str

通过验证安全删除文件。

"Delete the file ~/temp/old_data.csv"

目录操作

list_directory(path: str = ".", show_hidden: bool = False, detailed: bool = False) -> str

列出带有可选详细信息的目录内容。

"List all files in ~/Documents"
"Show detailed information for files in the current directory"
"List hidden files in ~/.config"

find_files(directory: str = ".", pattern: str = "*", recursive: bool = True, max_results: int = 100) -> str

查找与模式匹配的文件。

"Find all Python files in ~/projects"
"Find all *.md files in the current directory, non-recursively"
"Find all test_*.py files"

create_directory(path: str, parents: bool = True) -> str

创建一个新目录。

"Create a directory at ~/projects/new-app/src"

organize_directory(directory: str = ".", by: str = "type", dry_run: bool = False) -> str

将文件组织到子目录中。

组织方式：

  • type：按文件扩展名（文档、图像、视频、音频、代码、档案、其他）
  • date：按修改日期（YYYY-MM文件夹）
  • size：按文件大小（小、中、大）
"Organize ~/Downloads by file type"
"Organize the current directory by date (dry run first)"
"Organize ~/Desktop by size"

文本处理

count_words(text: str) -> str

分析文本统计数据（单词、字符、行）。

"Count the words in this text: [your text here]"

search_text(text: str, query: str, case_sensitive: bool = False) -> str

搜索包含上下文片段的文本。

"Search for 'function' in this code: [your code here]"
"Search for 'TODO' (case sensitive) in the text"

数学运算

calculate(expression: str) -> str

安全地计算数学表达式。

支持的功能： abs、舍入、最小值、最大值、和、幂、sqrt、sin、cos、tan、log、log10、exp、pi、e

"Calculate 2 + 2 * 3"
"Calculate sqrt(144)"
"Calculate sin(pi/2)"
"Calculate log10(1000)"

add_numbers(a: float, b: float) -> str

加两个数字。

multiply_numbers(a: float, b: float) -> str

将两个数字相乘。

公用事业

get_greeting(name: str) -> str

生成个性化问候语。

get_current_time(timezone: str = "local") -> str

获取当前日期和时间。

"What's the current time?"

🔍 资源

server://info

获取全面的服务器信息，包括所有可用的工具和功能。

"Show me information about the server capabilities"

📋 提示词

code_review_prompt(code: str, language: str = "python")

生成一个全面的代码审查模板。

file_analysis_prompt(file_path: str)

生成文件分析模板。

🎯 示例用例

整理一个杂乱的下载文件夹

Preview organization:
"Organize ~/Downloads by type with dry_run=true"

Apply changes:
"Organize ~/Downloads by type"

批量文本替换

"Update all TODO comments to DONE in ~/project/main.py"

查找和分析代码文件

"Find all Python files in ~/projects/myapp"
"Read ~/projects/myapp/src/main.py"
"Count the words in the file"

创建项目结构

"Create directories at ~/projects/new-app/src, ~/projects/new-app/tests, ~/projects/new-app/docs"
"Write a README.md template to ~/projects/new-app/README.md"

文件组织工作流

1. "List files in ~/Desktop with details"
2. "Organize ~/Desktop by type with dry_run=true" (preview)
3. "Organize ~/Desktop by type" (apply)

🔐 安全考虑

文件系统访问

  • 服务器可以访问您的整个文件系统
  • 操作前始终验证路径
  • 使用 dry_run=true 用于组织操作以预览更改
  • 服务器尊重文件权限，并将报告权限错误

网络部署

  • 使用HTTP传输时，请考虑：
    • 绑定到 127.0.0.1 （仅限本地主机）用于本地测试
    • 实施生产使用身份验证
    • 在生产环境中使用HTTPS
    • 使用防火墙规则限制访问

计算器安全

  • 这 calculate() 函数使用受限环境
  • 只有数学函数可用（没有文件I/O，没有系统调用）
  • 评估用户提供的表达式是安全的

🛠️ 发展

项目结构

mcp-local/
├── main.py              # Main server code
├── README.md            # This file
├── pyproject.toml       # Project metadata and dependencies
└── .python-version      # Python version specification

运行测试

# Test individual tools
fastmcp dev main.py

# Use MCP Inspector for interactive testing
fastmcp dev main.py

添加新工具

  1. 添加工具功能 @mcp.tool() 装饰器
  2. 在参数和返回值中包含正确的docstring
  3. 添加错误处理
  4. 更新 get_server_info() 资源
  5. 彻底测试

例子：

@mcp.tool()
def my_new_tool(param: str) -> str:
    """Description of what the tool does.
    
    Args:
        param: Description of parameter
    
    Returns:
        Description of return value
    """
    try:
        # Implementation
        return f"✓ Success: {result}"
    except Exception as e:
        return f"❌ Error: {e}"

📖 资源

🤝 贡献

欢迎投稿！请随时提交问题或拉取请求。

📄 许可证

MIT许可证-您可以自由地将此项目用于任何目的。

🐛 故障排除

服务器无法启动

问题：端口已在使用中

# Find and kill the process
lsof -i :8000
kill -9 <PID>

问题：访问文件时权限被拒绝

  • 检查文件权限： ls -la <path>
  • 确保服务器具有读/写访问权限

Claude桌面集成

问题：服务器未在Claude中显示

  1. 检查配置文件路径和语法（有效的JSON）
  2. 确保使用绝对路径
  3. 完全重新启动克劳德桌面
  4. 检查Claude Desktop日志是否有错误

问题：工具不工作

  1. 验证服务器是否正在运行：检查🔌 图标
  2. 尝试手动运行服务器以查看错误
  3. 检查Python和uv版本

常见错误

“文件不存在”

  • 验证路径是否正确
  • 使用绝对路径或 ~ 用于主目录
  • 检查文件名中的拼写错误

“权限被拒绝”

  • 检查文件/目录权限
  • 没有适当的权限，不要尝试访问系统文件
  • 在Windows上，某些系统目录需要管理员访问权限

💡 提示

  1. 使用选项卡完成：在Claude中，开始键入文件路径，它可能会建议完成
  2. 预览操作：使用 dry_run=true 用于组织运营
  3. 相对路径：服务器解析与其运行位置相关的路径
  4. 主目录：使用 ~ 用于跨平台主目录访问
  5. 批量操作：使用 find_files() 要获取列表，请对每个文件进行操作

🎓 学习资源

FastMCP基础知识

  • 从简单的工具开始，比如 get_greeting() 和 add_numbers()
  • 使用安全的测试文件探索文件操作
  • 尝试使用各种表达式的计算器

MCP协议

  • 了解资源、工具和提示
  • 了解不同的运输方式
  • 探索MCP检查器工具

最佳实践

  • 始终优雅地处理错误
  • 提供信息丰富的成功/错误消息
  • 使用类型提示以获得更好的IDE支持
  • 编写全面的文档字符串

内置于❤️ 使用FastMCP

如有疑问或支持，请在GitHub上发布问题。

相关 MCP