Servidor MCP JSONPlaceholder

Un servidor Model Context Protocol (MCP) que expone funciones para consultar la API de JSONPlaceholder (https://jsonplaceholder.typicode.com).

🚀 Características

• Consulta de Posts: Obtener todos los posts, filtrar por usuario o obtener un post específico

• Gestión de Usuarios: Listar todos los usuarios o obtener información de un usuario específico

• Comentarios: Obtener comentarios de posts específicos o todos los comentarios

• Creación de Posts: Crear nuevos posts (simulado)

• API Asíncrona: Manejo eficiente de requests HTTP con httpx

• Manejo de Errores: Gestión robusta de errores HTTP y excepciones

Related MCP server: todoist

📦 Instalación

1. Instalar dependencias:

   pip install -r requirements.txt

🔧 Configuración para Claude Desktop

Para conectar este servidor MCP con Claude Desktop:

1. Localizar el archivo de configuración de Claude Desktop:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Añadir la configuración del servidor:

   {
     "mcpServers": {
       "jsonplaceholder": {
         "command": "python",
         "args": ["c:\\Users\\Dell3\\IdeaProjects\\MyFirstMCP\\server.py"],
         "env": {}
       }
     }
   }

   ⚠️ Importante: Ajusta la ruta en args según tu ubicación del proyecto.

3. Reiniciar Claude Desktop para que cargue la nueva configuración.

🎮 Uso

Iniciar el Servidor

# Opción 1: Script automático
start_server.bat

# Opción 2: Manual
python server.py

Probar el Cliente

python client_test.py

🛠️ Funciones Disponibles

1. get_posts

Obtiene posts de JSONPlaceholder.

Parámetros:

• user_id (opcional): ID del usuario para filtrar posts

• post_id (opcional): ID específico del post a obtener

Ejemplos:

# Obtener todos los posts
await mcp.call_tool("get_posts", {})

# Obtener posts del usuario 1
await mcp.call_tool("get_posts", {"user_id": 1})

# Obtener post específico
await mcp.call_tool("get_posts", {"post_id": 5})

2. get_users

Obtiene usuarios de JSONPlaceholder.

Parámetros:

• user_id (opcional): ID específico del usuario a obtener

Ejemplos:

# Obtener todos los usuarios
await mcp.call_tool("get_users", {})

# Obtener usuario específico
await mcp.call_tool("get_users", {"user_id": 3})

3. get_comments

Obtiene comentarios de JSONPlaceholder.

Parámetros:

• post_id (opcional): ID del post para obtener sus comentarios

Ejemplos:

# Obtener todos los comentarios
await mcp.call_tool("get_comments", {})

# Obtener comentarios de un post específico
await mcp.call_tool("get_comments", {"post_id": 1})

4. create_post

Crea un nuevo post (simulado).

Parámetros (obligatorios):

• title: Título del post

• body: Contenido del post

• user_id: ID del usuario que crea el post

Ejemplo:

await mcp.call_tool("create_post", {
    "title": "Mi Nuevo Post",
    "body": "Contenido del post...",
    "user_id": 1
})

🧪 Usando con Claude

Una vez configurado, puedes usar las funciones directamente en Claude:

"Obtén todos los posts del usuario 1"
"Muéstrame los comentarios del post 5" 
"Crea un nuevo post con título 'Hola Mundo' y contenido 'Este es mi primer post'"
"¿Cuántos usuarios hay registrados?"

📁 Estructura del Proyecto

MyFirstMCP/
├── server.py                  # Servidor MCP principal
├── client_test.py            # Cliente de prueba
├── requirements.txt          # Dependencias Python
├── claude_desktop_config.json # Configuración para Claude Desktop
├── install.bat              # Script de instalación
├── start_server.bat         # Script para iniciar servidor
├── test_client.bat          # Script para probar cliente
└── README.md               # Esta documentación

🐛 Resolución de Problemas

Error: "Módulo mcp no encontrado"

pip install mcp

Error: "No se puede conectar al servidor"

1. Verifica que Python esté en el PATH

2. Confirma que la ruta en claude_desktop_config.json sea correcta

3. Reinicia Claude Desktop después de cambiar la configuración

Error de permisos en Windows

Ejecuta el terminal como administrador o ajusta la ruta del proyecto.

🔗 Enlaces Útiles

• JSONPlaceholder API

• Model Context Protocol

• Claude Desktop

📝 Licencia

Este proyecto es de código abierto.