Python MCP Custom Server

# 🐍 Servidor MCP Personalizado en Python

Un servidor MCP (Model Context Protocol) completo desarrollado en Python que extiende las capacidades de Claude Desktop con herramientas personalizadas para gestión de archivos, sistema operativo y más.

## 📖 Sobre este Proyecto

Este proyecto nació de mi curiosidad por explorar el Model Context Protocol y crear herramientas personalizadas que hicieran a Claude más útil en mi flujo de trabajo diario. Después de investigar la documentación oficial y experimentar con diferentes enfoques, logré implementar un servidor robusto con múltiples funcionalidades.

Lo que comenzó como un simple script para crear archivos se convirtió en un conjunto completo de herramientas que utilizo regularmente. He documentado todo el proceso aquí para que otros puedan aprender y construir sobre este trabajo.

## ✨ Características

- ✅ **Gestión de Archivos**: Crear, leer, eliminar y buscar archivos
- 📁 **Organización**: Crear carpetas y listar directorios
- 💻 **Info del Sistema**: Obtener detalles del hardware y SO
- ⚙️ **Ejecución de Comandos**: Ejecutar comandos de terminal de forma segura
- 📊 **Análisis de Archivos**: Obtener tamaños y estadísticas
- 🔍 **Búsqueda Avanzada**: Buscar archivos por patrones

## 🛠️ Stack Tecnológico

- **Python 3.10+**: Lenguaje principal
- **MCP SDK**: Framework para el servidor
- **VS Code**: Entorno de desarrollo
- **Claude Desktop**: Cliente para las herramientas
- **psutil**: Información del sistema
- **aiofiles**: Operaciones de archivos asíncronas

## 📋 Requisitos Previos

Antes de comenzar, asegúrate de tener instalado:

- Python 3.10 o superior
- pip (gestor de paquetes de Python)
- VS Code (opcional, pero recomendado)
- Claude Desktop

## 🚀 Instalación

### 1. Clonar o Descargar el Proyecto

```bash
git clone https://github.com/tu-usuario/MCP.git
cd MCP/servidor-mcp-python
```

### 2. Crear Entorno Virtual

Es importante trabajar con un entorno virtual para evitar conflictos de dependencias:

```bash
# Crear el entorno virtual
python -m venv venv

# Activar el entorno virtual
# En Windows:
venv\Scripts\activate

# En macOS/Linux:
source venv/bin/activate
```

Deberías ver `(venv)` al inicio de tu línea de comandos.

### 3. Instalar Dependencias

```bash
pip install -r requirements.txt
```

### 4. Verificar la Instalación

Prueba que el servidor arranca correctamente:

```bash
python src/server.py
```

Si ves el mensaje "🚀 Servidor MCP Python iniciado correctamente", ¡todo está listo!

Presiona `Ctrl+C` para detener el servidor.

## ⚙️ Configuración con Claude Desktop

Para que Claude Desktop pueda usar este servidor, necesitas editar su archivo de configuración.

### Paso 1: Abrir el Directorio de Configuración

1. Presiona `Windows + R`
2. Pega esto: `%APPDATA%\Claude`
3. Presiona Enter

### Paso 2: Editar el Archivo de Configuración

Abre el archivo `claude_desktop_config.json` con tu editor de texto favorito (yo uso VS Code).

### Paso 3: Añadir la Configuración del Servidor

Añade esta configuración (ajusta las rutas según tu instalación):

```json
{
	"mcpServers": {
		"mi-servidor-python": {
			"command": "C:\\ruta\\al\\proyecto\\venv\\Scripts\\python.exe",
			"args": [
				"C:\\ruta\\al\\proyecto\\src\\server.py"
			]
		}
	}
}
```

**Nota:** Reemplaza `C:\\ruta\\al\\proyecto` con la ruta absoluta donde hayas clonado este repositorio.

### Paso 4: Reiniciar Claude Desktop

1. Cierra completamente Claude Desktop
2. Vuelve a abrirlo
3. Abre una conversación nueva

## 🎯 Uso

Una vez configurado, puedes usar las herramientas directamente en Claude Desktop:

### Ejemplos de Uso

```
Crea un archivo en mi escritorio llamado "notas.txt" con el contenido "Lista de tareas: ..."
```

```
Lista todos los archivos en mi escritorio
```

```
Dame información sobre mi sistema operativo
```

```
Busca todos los archivos .py en mi carpeta de documentos
```

## 🔧 Herramientas Disponibles

| Herramienta | Descripción |
|-------------|-------------|
| `crear_archivo_escritorio` | Crea archivos de texto en el escritorio |
| `leer_archivo` | Lee el contenido de cualquier archivo |
| `listar_archivos` | Lista el contenido de un directorio |
| `eliminar_archivo` | Elimina archivos del sistema |
| `crear_carpeta` | Crea nuevas carpetas |
| `info_sistema` | Muestra información del hardware y SO |
| `ejecutar_comando` | Ejecuta comandos de terminal |
| `buscar_archivos` | Busca archivos por patrón |
| `obtener_tamano_archivo` | Obtiene el tamaño de archivos |

## 📁 Estructura del Proyecto

```
servidor-mcp-python/
├── venv/                    # Entorno virtual (no incluido en Git)
├── src/
│   └── server.py           # Código principal del servidor
├── requirements.txt         # Dependencias del proyecto
├── README.md               # Este archivo
└── .gitignore              # Archivos ignorados por Git
```

## 🐛 Solución de Problemas

### El servidor no arranca

**Problema:** Al ejecutar `python src/server.py` no pasa nada o da error.

**Solución:** 
- Verifica que el entorno virtual esté activado (debes ver `(venv)`)
- Reinstala las dependencias: `pip install -r requirements.txt`

### Claude no ve las herramientas

**Problema:** Claude Desktop no muestra las herramientas del servidor.

**Solución:**
- Verifica que las rutas en `claude_desktop_config.json` sean correctas
- Usa barras invertidas dobles `\\` en Windows
- Asegúrate de usar la ruta del Python del entorno virtual, no del sistema
- Reinicia Claude Desktop completamente

### Errores de permisos

**Problema:** El servidor no puede crear o modificar archivos.

**Solución:**
- Ejecuta Claude Desktop con permisos de administrador (solo si es necesario)
- Verifica que tengas permisos de escritura en los directorios que usas

## 🎓 Lo que Aprendí

Durante el desarrollo de este proyecto, enfrenté varios desafíos interesantes:

1. **Manejo de rutas en Windows**: Aprendí la importancia de usar `Path` de `pathlib` en lugar de concatenar strings para rutas.

2. **Programación asíncrona**: Fue mi primera vez trabajando seriamente con `async/await` en Python. La curva de aprendizaje fue empinada, pero valió la pena.

3. **Seguridad**: Implementar la herramienta de ejecución de comandos me hizo consciente de los riesgos de seguridad. Añadí timeouts y validaciones para mitigar problemas.

4. **Debugging de servidores MCP**: Los logs de Claude Desktop fueron cruciales. Aprendí a usar `sys.stderr` para debug sin interferir con el protocolo.

## 🔮 Futuras Mejoras

Tengo varias ideas para expandir este proyecto:

- [ ] Integración con bases de datos (SQLite, PostgreSQL)
- [ ] Soporte para operaciones con imágenes
- [ ] Herramientas para trabajar con APIs REST
- [ ] Análisis de datos con pandas
- [ ] Sistema de plugins para añadir herramientas fácilmente
- [ ] Tests unitarios completos

## 📚 Recursos que Usé

- [Documentación oficial de MCP](https://modelcontextprotocol.io)
- [Python SDK de MCP](https://github.com/modelcontextprotocol/python-sdk)
- [Documentación de asyncio](https://docs.python.org/3/library/asyncio.html)
- [Claude Desktop Docs](https://support.claude.com)

## 🤝 Contribuciones

Este es un proyecto personal de aprendizaje, pero si encuentras bugs o tienes sugerencias, ¡son bienvenidas! Abre un issue o envía un pull request.

## 📝 Licencia

Este proyecto está bajo la Licencia MIT. Siéntete libre de usarlo, modificarlo y distribuirlo.

## 👤 Autor

Desarrollado con ☕ y mucha experimentación.

Si este proyecto te fue útil, considera darle una ⭐ en GitHub.

---

**Nota:** Este README asume conocimientos básicos de Python y línea de comandos. Si encuentras algo confuso, no dudes en abrir un issue para que pueda mejorar la documentación.