ZIN MCP Client

Nota de archivo:

En primer lugar, gracias a todos los que apoyaron este proyecto. Pero tengo que ponerlo en modo de solo lectura y abandonar futuros desarrollos debido a las siguientes razones:

• Otros proyectos: Tengo que trabajar en otros proyectos que son mucho más útiles
• Limitación de recursos: Debido al tiempo y recursos limitados, no puedo añadir más funciones
• Mejores alternativas: Incluso si trabajara en este proyecto y añadiera muchas más funciones, el resultado final no tendría sentido, ya que dichas funciones relacionadas con el cliente MCP ya están implementadas en otras alternativas. Por eso quiero dedicar ese tiempo a otros proyectos como Jadx AI MCP
• Objetivo alcanzado: El objetivo inicial de este proyecto era crear un cliente MCP ligero basado en CLI para poder probar mis servidores MCP. Añadir más funciones solo lo convertiría en algo que no está destinado a ser. Por ejemplo, la actualización de interfaz web que implementé, pero están fuera de lugar ya que existen alternativas mucho mejores.

Imagen generada con herramientas de IA.

---

🤖 ¿Qué es ZIN MCP Client?

Una herramienta potente pero ligera, rápida, simple y flexible para interactuar con servidores MCP (Model Context Protocol) a través de LLM locales. Esta herramienta te permite conectarte y utilizar diversas herramientas de múltiples servidores MCP mediante una interfaz de línea de comandos fácil de usar.

¡Mira las demostraciones!

• Interacción CLI enriquecida

https://github.com/user-attachments/assets/fad3d994-8113-47df-b10c-54541a5c3aec

• Realiza revisiones de código para encontrar vulnerabilidades localmente

https://github.com/user-attachments/assets/4cd26715-b5e6-4b4b-95e4-054de6789f42

• Soporte Plug n Play para Open Web UI

https://github.com/user-attachments/assets/94e1ff33-0c88-40a8-8447-d9c3278a1d50

• Soporta múltiples servidores - Servidor GhidraMCP

https://github.com/user-attachments/assets/759f7138-1cc5-400f-b7e2-a6a7f0dca894

• Interfaz web ligera

https://github.com/user-attachments/assets/704c214b-0ebb-4da9-971c-5f04446e9646

Características

• Soporte multi-servidor: Conéctate a múltiples servidores MCP simultáneamente
• Integración con LLM local: Usa LLM locales a través de Ollama para privacidad y control
• CLI interactivo: Interfaz de línea de comandos limpia e intuitiva con formato enriquecido
• Interfaz web mínima y ligera: Interfaz web limpia, mínima y ligera para facilidad de uso
• Integración con Open Web UI: Integración Plug n Play con Open Web UI para obtener las funciones enriquecidas de Open Web UI con un potente cliente MCP
• Registro completo: Registros detallados para depuración y resolución de problemas
• Framework de agente ReAct: Utiliza el patrón de agente ReAct de LangChain para invocar herramientas de forma inteligente
• Multiplataforma: Soporte multiplataforma
• Simple, rápido, ligero: Es simple, es rápido, es ligero

---

Consulta la Suite MCP de Zin

[!NOTE]

Este proyecto está en desarrollo activo. Espera cambios importantes con los lanzamientos. Revisa el registro de cambios de la versión antes de actualizar.
Este proyecto está construido principalmente para usarse con LLM locales para uso personal a pequeña escala únicamente. Exponerlo en la red puede suponer un riesgo de seguridad y, por tanto, no se recomienda.
:--------------------------------
Este proyecto está desarrollado principalmente para los Servidores MCP de Zin, que son los servidores MCP mencionados a continuación, pero el soporte para otros servidores MCP existe y también se han realizado pruebas en otros servidores MCP como Ghidra

• APKTool-MCP-Server
• JADX-MCP-Server

🛠️ Primeros pasos

1. Descarga desde Releases: https://github.com/zinja-coder/zin-mcp-client/releases

# 1. 
unzip zin-mcp-client-<version>.zip

├zin-mcp-client/
  ├── zin_mcp_client.py
  ├── web_client.py
  ├── mcp_proxy.py
  ├── static/
  ├── src/
  ├── mcp-config.json
  ├── README.md
  ├── LICENSE

# 2. Navigate to zin-mcp-client directory
cd zin-mcp-client

# 3. This project uses uv (recommended) - https://github.com/astral-sh/uv instead of pip for dependency management.
    ## a. Install uv (if you dont have it yet) - (Only Required Step)
curl -LsSf https://astral.sh/uv/install.sh | sh

# All below steps are not required.
    ## b. OPTIONAL, if for any reasons, you get dependecy errors in jadx-mcp-server, Set up the environment
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
    ## c. OPTIONAL Install dependencies
uv pip install -r requirements.txt

# 4. Not recommended, you can also use pip for this.
pip install -r requirements.txt
or
pip install -r requirements.txt --break-system-packages

# The setup for zin-mcp-client is done.

🤖 2. Configuración de Ollama

1. Download and Install ollama: https://ollama.com/download

If you are on linux you can directly run below command to install it:

> curl -fsSL https://ollama.com/install.sh | sh

2. Download and run any LLM that has capability to invoke tool.

For example, the llama 3.1 has capability to invoke the tool. 

You can run it using following command:

> ollama run llama3.1:8b

[Note]: Kindly note the above command will fetch the model with 4b parameters. If you have stronger hardware kindly fetch higher parameter model for better performance.

3. Serve the Ollama on API server using following command

> ollama serve

This will serve the ollama api on port 1134, you can confirm that it running using `curl` command as following:

> curl http://localhost:11434/                                                                                                                                              18:54:00
`Ollama is running`

⚙️ 3. Configuración del archivo de configuración

El archivo de configuración es el archivo de configuración del servidor MCP que le indica al cliente MCP de Zin cómo iniciar los servidores MCP.

Sigue el mismo estilo que el archivo de configuración de Claude.

A continuación se muestra el archivo de configuración de ejemplo para los servidores de la Suite MCP de Zin:

{
    "mcpServers": {
        "jadx-mcp-server": {
            "command": "/path/to/uv", 
            "args": [
                "--directory",
                "/path/to/jadx-mcp-server/",
                "run",
                "jadx_mcp_server.py"
            ]
        },
        "apktool-mcp-server": {
		    "command": "/path/to/uv",
            "args": [
                "--directory",
                "/path/to/apktool-mcp-server/",
                "run",
                "apktool_mcp_server.py"
            ]
	}
    }
}

Reemplaza:

• path/to/uv con la ruta real a tu ejecutable de uv
• path/to/jadx-mcp-server con la ruta absoluta donde hayas guardado el jadx-mcp-server

[!NOTE]

La ubicación predeterminada del archivo de configuración está dentro del directorio zin-mcp-client con el nombre mcp-config.json, sin embargo, puedes proporcionar la ruta a tu propio archivo de configuración usando la opción --config como por ejemplo

uv run zin_mcp_client.py --server jadx-mcp-server --model llama3.1:8b --config /home/zinjacoder/mcp-config.json 

Pruébalo

1. Ejecuta zin_mcp_client.py

uv run zin_mcp_client.py

2. Usa la opción --server para especificar el servidor de tu elección, usa la opción --config para proporcionar la ruta a tu archivo de configuración, usa la opción --model para usar un modelo específico, usa --debug para habilitar la salida detallada

Si algo salió mal - DEPURACIÓN y resolución de problemas

[!NOTE]

Para sistemas de bajos recursos, usa solo un servidor a la vez para evitar alucinaciones del LLM.

1. Revisa los registros:

• Todos los registros, información de depuración, tráfico bruto e interacciones se almacenan en registros de forma fácil de leer. Si algo sale mal, revisa los registros.

2. Modo de depuración:

• También puedes usar la bandera --debug para habilitar la depuración e imprimir cada detalle en la consola en tiempo de ejecución para ayudarte a encontrar el problema.

https://github.com/user-attachments/assets/ee478917-c4f5-46fb-9f0e-ad31d7c33ee0

3. Abre un issue:

• Si no puedes resolver el error por tu cuenta, usa los registros y la salida del modo de depuración y proporciónanoslos abriendo un issue en https://github.com/zinja-coder/zin-mcp-client/issues

Cliente web

1. Completa la configuración mencionada anteriormente
2. Ejecuta el cliente web usando lo siguiente:

uv run web_client.py

3. La demostración del cliente web se muestra en el video en la parte superior

Configuración con Open Web UI

1. Completa la configuración mencionada anteriormente.
2. Ejecuta el proxy MCP usando lo siguiente:

uv run mcp_proxy.py

3. Ve al portal de Open Web UI.
4. En Open Web UI -> Configuración -> Conexión -> añade una nueva conexión como se muestra en la siguiente imagen

Añade la URL del proxy MCP que se ejecuta en el puerto 8000 con localhost si se ejecuta localmente, como se muestra en la imagen. Puedes poner cualquier cosa en la clave de API.

5. Ahora solicita y utiliza el cliente MCP, configuración Plug n Play.

---

Estado actual de los LLM locales y los MCP:

Actualmente, los modelos propietarios basados en API como Claude de Anthropic tienden a ser más competentes en la llamada de herramientas.

¡Sin embargo, el mundo del código abierto avanza rápidamente! Los modelos específicamente ajustados con conjuntos de datos de llamada de funciones están cada vez más disponibles a través de Ollama. Investigar modelos etiquetados con function calling o tool use en plataformas como Hugging Face o consultar discusiones en comunidades como r/LocalLLaMA es clave para encontrar opciones locales capaces.

---

🛣️ Hoja de ruta futura

• Interfaz web

• Integración con Open Web UI

• Añadir soporte para servidores MCP basados en HTTP - Porque muchos servidores proporcionan una forma de hacer que sus servidores actúen como STDIO.

• Añadir soporte para exponer este cliente en la red también, indirectamente para acceso a la red - hecho indirectamente a través de la integración con open web ui

• Almacenar el chat localmente y proporcionar historial de chat - hecho indirectamente a través de la integración con open web ui

• OBJETIVO FINAL: Reunir todos los servidores MCP de ingeniería inversa para hacer que la ingeniería inversa sea lo más fácil posible puramente desde la intuición.

Para reportar errores, problemas, sugerencias de funciones, problemas de rendimiento, preguntas generales, problemas de documentación.

• Abre un issue con la plantilla correspondiente.

• Probado en entornos Mac OS y Linux con jadx-mcp-server y Ghidra MCP Server

🙏 Créditos

Este proyecto es posible gracias a ollama, una increíble utilidad para ejecutar LLM locales. El proyecto langchain,

Y por último, gracias a @anthropics por desarrollar el Model Context Protocol y al equipo de @FastMCP.

Además, un enorme agradecimiento a todos los proyectos de código abierto que sirven como dependencias para este proyecto y que hicieron esto posible.

📄 Licencia

ZIN MCP Client y todos los proyectos relacionados heredan la Licencia Apache 2.0.

⚖️ Advertencia legal

Descargo de responsabilidad

Las herramientas zin-mcp-client y zin mcp suite están destinadas estrictamente a fines educativos, de investigación y evaluación ética de seguridad. Se proporcionan "tal cual" sin garantías, expresas o implícitas. Los usuarios son los únicos responsables de garantizar que su uso de estas herramientas cumpla con todas las leyes, regulaciones y pautas éticas aplicables.

Al usar zin-mcp-client o zin mcp suite, aceptas usarlas solo en entornos que estás autorizado a probar, como aplicaciones que posees o para las que tienes permiso explícito de analizar. Cualquier uso indebido de estas herramientas para ingeniería inversa no autorizada, infracción de derechos de propiedad intelectual o actividad maliciosa está estrictamente prohibido.

Los desarrolladores de zin-mcp-client y zin mcp suite no serán responsables de ningún daño, pérdida de datos, consecuencias legales u otras consecuencias resultantes del uso o mal uso de estas herramientas. Los usuarios asumen toda la responsabilidad por sus acciones y cualquier impacto causado por su uso.

Usa responsablemente. Respeta la propiedad intelectual. Sigue prácticas de hacking ético.

---

🙌 Contribuye o apoya

• ¿Te resultó útil? Dale una ⭐️
• ¿Tienes ideas? Abre un issue o envía un PR
• ¿Construiste algo encima? Escríbeme o mencióname — ¡lo añadiré al README!
• ¿Te gusta mi trabajo y quieres que continúe? Patrocina este proyecto.

---

Construido con ❤️ para las comunidades de ingeniería inversa e IA y todos los increíbles hackers y contribuyentes de código abierto de todo el mundo.