MCP Custom Tools Server
Un servidor MCP (Model Context Protocol) personalizado con un conjunto completo de herramientas para fecha/hora, manejo de archivos, información del sistema, procesamiento de texto y operaciones web.
Características
- ✅ Servidor MCP completo implementado desde cero
- ✅ Gestión moderna de dependencias con
pyproject.toml - ✅ 30+ herramientas personalizadas organizadas por categorías
- ✅ Comunicación asíncrona con soporte para stdio
- ✅ Logging configurable y manejo de errores robusto
- ✅ CLI integrado con opciones flexibles
Herramientas Disponibles
🕒 Fecha y Hora (datetime_tools)
current_time- Obtener fecha y hora actualformat_timestamp- Formatear timestamp a formato legiblecalculate_age- Calcular edad a partir de fecha de nacimientodays_between- Calcular días entre dos fechasmonth_calendar- Generar calendario mensual
📁 Manejo de Archivos (file_tools)
read_file- Leer contenido de archivo (async/sync)file_info- Obtener información detallada de archivolist_directory- Listar contenido de directoriocalculate_hash- Calcular hash MD5/SHA256 de archivosearch_files- Buscar archivos por patrón
💻 Sistema (system_tools)
system_info- Información general del sistemacpu_info- Información detallada de CPUmemory_info- Información de memoria RAMdisk_info- Información de discos y almacenamientonetwork_info- Información de interfaces de redprocess_list- Lista de procesos en ejecuciónenvironment_vars- Variables de entorno del sistema
📝 Procesamiento de Texto (text_tools)
word_count- Contar palabras, líneas y caracteressearch_replace- Búsqueda y reemplazo con regexextract_emails- Extraer direcciones de emailextract_urls- Extraer URLs de textotext_analysis- Análisis detallado de textoencode_decode- Codificación/decodificación de textogenerate_hash- Generar hash de textosplit_text- Dividir texto en chunks
🌐 Web (web_tools)
http_request- Realizar peticiones HTTPparse_url- Parsear y analizar URLsbuild_url- Construir URLs desde componentesurl_encode_decode- Codificar/decodificar URLsvalidate_url- Validar formato y accesibilidadextract_domain- Extraer información de dominio
Instalación
Prerrequisitos
- Python 3.10+
- uv (gestor de paquetes y entornos virtuales moderno)
Instalación desde código fuente
# Clonar el repositorio
git clone <repository-url>
cd mcp-custom-tools
# Instalar uv (si no lo tienes)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Instalar dependencias y crear entorno virtual automáticamente
uv sync
# Instalar dependencias de desarrollo
uv sync --group dev
# Verificar instalación
uv run mcp-server --help
Uso
Ejecutar el servidor
# Método recomendado - usando el script instalado
uv run mcp-server
# Con nivel de logging específico
uv run mcp-server --log-level DEBUG
# Con configuración personalizada
uv run mcp-server --log-level INFO --name "Mi Servidor MCP" --version "1.0.0"
# Método alternativo - usando módulo Python
uv run python -m mcp_custom_tools.server
# Con configuración personalizada usando módulo
uv run python -m mcp_custom_tools.server --log-level INFO --name "Custom Server"
Opciones de CLI
--log-level- Nivel de logging (DEBUG, INFO, WARNING, ERROR)--name- Nombre del servidor MCP--version- Versión del servidor--help- Mostrar ayuda
⚠️ Importante: Usar siempre uv run
En Windows, los scripts instalados con uv no están disponibles globalmente en PATH. Siempre usa:
# ✅ Correcto
uv run mcp-server
# ❌ Error - No funciona
mcp-server
Integración con clientes MCP
El servidor usa comunicación stdio y es compatible con cualquier cliente MCP estándar.
Configuración JSON:
{
"mcpServers": {
"mcp-custom-tools": {
"command": "uv",
"args": [
"run",
"mcp-server",
"--log-level",
"INFO"
],
"cwd": "/path/to/mcp-custom-tools"
}
}
}
Ejemplos de rutas por sistema operativo:
// Windows
"cwd": "C:\\Users\\TuUsuario\\mcp-custom-tools"
// macOS/Linux
"cwd": "/home/tuusuario/mcp-custom-tools"
// o
"cwd": "~/mcp-custom-tools"
Configuración para otros clientes MCP
Para otros clientes que soporten MCP, usar la siguiente configuración base:
{
"name": "mcp-custom-tools",
"command": ["uv", "run", "mcp-server"],
"args": ["--log-level", "INFO"],
"cwd": "/path/to/mcp-custom-tools"
}
Verificar la configuración
- Reinicia Claude Desktop después de modificar la configuración
- Abre una nueva conversación en Claude
- Verifica las herramientas escribiendo: "¿Qué herramientas tienes disponibles?"
- Prueba una herramienta como: "¿Qué hora es ahora?"
Solución de problemas
Si el comando 'mcp-server' no se reconoce:
Este es el error más común en Windows. El script se instala en el entorno virtual pero no está en PATH global.
# ❌ Error común
mcp-server
# Error: 'mcp-server' no se reconoce como comando
# ✅ Solución
uv run mcp-server
Si el servidor no se conecta:
- Verificar que
"cwd"apunte al directorio correcto del proyecto - Verificar uv: Comprobar que uv esté instalado:
uv --version - Sincronizar proyecto: Ejecutar
uv syncen el directorio del proyecto - Revisar logs: Verificar logs en Claude Desktop (Ver > Herramientas de desarrollador)
- Probar manualmente:
uv run mcp-server --log-level DEBUGdesde el directorio del proyecto
Logs y debugging:
# Probar el servidor directamente
uv run mcp-server --log-level DEBUG
# Verificar herramientas disponibles
uv run python -c "from mcp_custom_tools.tools import get_available_tools; print(list(get_available_tools().keys()))"
# Verificar que uv funciona correctamente
uv run python --version
# Verificar instalación del paquete
uv run python -c "import mcp_custom_tools; print('Instalación OK')"
Desarrollo
Estructura del Proyecto
mcp-custom-tools/
├── src/
│ └── mcp_custom_tools/
│ ├── __init__.py
│ ├── server.py
│ └── tools/
│ ├── __init__.py
│ ├── datetime_tools.py
│ ├── file_tools.py
│ ├── system_tools.py
│ ├── text_tools.py
│ └── web_tools.py
├── pyproject.toml
├── README.md
└── .gitignore
Configuración de Desarrollo
# Instalar dependencias de desarrollo
uv sync --group dev
# Ejecutar linting
black src/
isort src/
flake8 src/
mypy src/
# Ejecutar tests
pytest
# Ejecutar tests con cobertura
pytest --cov=mcp_custom_tools
Añadir Nuevas Herramientas
- Crear nueva función de herramienta:
def my_new_tool(args: Dict[str, Any]) -> str:
"""Mi nueva herramienta."""
# Implementación
return "resultado"
- Registrar en función de registro:
def register_my_tools(tools: Dict[str, Dict[str, Any]]) -> None:
tools["my_tool"] = {
"description": "Descripción de mi herramienta",
"handler": my_new_tool,
"inputSchema": {
"type": "object",
"properties": {
"param": {"type": "string", "description": "Parámetro"}
},
"required": ["param"]
}
}
- Importar y registrar en
tools/__init__.py
Dependencias
Principales
mcp- Protocolo MCP corehttpx- Peticiones HTTP asyncaiofiles- Operaciones de archivo asyncpsutil- Información del sistemaclick- CLI framework
Desarrollo
black- Formateo de códigoisort- Ordenamiento de importsmypy- Type checkingflake8- Lintingpytest- Testing framework
Licencia
MIT License - ver archivo LICENSE para detalles.
Contribuir
- Fork el proyecto
- Crear rama de feature (
git checkout -b feature/AmazingFeature) - Commit cambios (
git commit -m 'Add some AmazingFeature') - Push a la rama (
git push origin feature/AmazingFeature) - Abrir Pull Request
Soporte
Para reportar bugs o solicitar features, crear un issue en GitHub.
Changelog
v1.0.0
- Implementación inicial del servidor MCP
- 30+ herramientas personalizadas
- Gestión con pyproject.toml
- CLI integrado
- Documentación completa