Skip to content

Commit b91dce0

Browse files
zinja-coderzinja-coder
authored
Update README.md
1 parent 1f3ba38 commit b91dce0

File tree

1 file changed

+109
-167
lines changed

1 file changed

+109
-167
lines changed

‎README.md

Lines changed: 109 additions & 167 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,18 @@ A powerful yet lightweight, fast, simple and flexible client for interacting wit
3333
Watch the demos!
3434

3535

36+
- **Rich CLI interaction**
37+
38+
https://github.com/user-attachments/assets/fad3d994-8113-47df-b10c-54541a5c3aec
39+
40+
41+
42+
- **Perform Code Review to Find Vulnerabilities locally**
43+
44+
https://github.com/user-attachments/assets/4cd26715-b5e6-4b4b-95e4-054de6789f42
45+
46+
47+
3648
# Features
3749

3850
- **Multi-Server Support:** Connect to multiple MCP servers simultaneously
@@ -46,6 +58,11 @@ Watch the demos!
4658
---
4759

4860
# Check the Zin MCP Suite
61+
62+
> [!NOTE]
63+
>
64+
> This project is mainly developed for Zin MCP Servers which are below mentioned MCP Servers, while other STDIO based MCP Servers should work in theory testing is done on following servers only.
65+
4966
- **[APKTool-MCP-Server](https://github.com/zinja-coder/apktool-mcp-server)**
5067
- **[JADX-MCP-Server](https://github.com/zinja-coder/jadx-mcp-server)**
5168

@@ -63,135 +80,33 @@ unzip zin-mcp-client-<version>.zip
6380
├zin-mcp-client/
6481
├── zin_mcp_client.py
6582
├── src/
83+
├── mcp-config.json
6684
├── README.md
6785
├── LICENSE
6886

69-
# 2. Install the plugin
70-
71-
# For this you can follow two approaches:
72-
73-
## 1. One liner - execute below command in your shell
74-
jadx plugins --install "github:zinja-coder:jadx-ai-mcp"
75-
76-
## The above one line code will install the latest version of the plugin directly into the jadx, no need to download the jadx-ai-mcp's .jar file.
77-
## 2. Or you can use JADX-GUI to install it by following images as shown below:
78-
```
79-
![img.png](docs/assets/img_1231.png)
80-
![img_1.png](docs/assets/img_1123.png)
81-
![img_2.png](docs/assets/img_2122.png)
87+
# 2. Navigate to zin-mcp-client directory
88+
cd zin-mcp-client
8289

83-
```bash
84-
## 3. GUI method, download the .jar file and follow below steps shown in images
85-
```
86-
![img.png](docs/assets/img123.png)
87-
![img_1.png](docs/assets/img_12.png)
88-
![img_2.png](docs/assets/img_2.png)
89-
![img_3.png](docs/assets/img_3.png)
90-
```bash
91-
# 3. Navigate to jadx-mcp-server directory
92-
cd jadx-mcp-server
93-
94-
# 4. This project uses uv - https://github.com/astral-sh/uv instead of pip for dependency management.
95-
## a. Install uv (if you dont have it yet)
90+
# 3. This project uses uv (recommended) - https://github.com/astral-sh/uv instead of pip for dependency management.
91+
## a. Install uv (if you dont have it yet) - (Only Required Step)
9692
curl -LsSf https://astral.sh/uv/install.sh | sh
93+
94+
# All below steps are not required.
9795
## b. OPTIONAL, if for any reasons, you get dependecy errors in jadx-mcp-server, Set up the environment
9896
uv venv
9997
source .venv/bin/activate # or .venv\Scripts\activate on Windows
10098
## c. OPTIONAL Install dependencies
101-
uv pip install httpx fastmcp
102-
103-
# The setup for jadx-ai-mcp and jadx_mcp_server is done.
104-
```
105-
106-
## 🤖 2. Claude Desktop Setup
107-
108-
Make sure Claude Desktop is running with MCP enabled.
109-
110-
For instance, I have used following for Kali Linux: https://github.com/aaddrick/claude-desktop-debian
111-
112-
Configure and add MCP server to LLM file:
113-
```bash
114-
nano ~/.config/Claude/claude_desktop_config.json
115-
```
99+
uv pip install -r requirements.txt
116100

117-
For:
118-
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
119-
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
120-
121-
And following content in it:
122-
```json
123-
{
124-
"mcpServers": {
125-
"jadx-mcp-server": {
126-
"command": "/<path>/<to>/uv",
127-
"args": [
128-
"--directory",
129-
"</PATH/TO/>jadx-mcp-server/",
130-
"run",
131-
"jadx_mcp_server.py"
132-
]
133-
}
134-
}
135-
}
136-
```
101+
# 4. Not recommended, you can also use pip for this.
102+
pip install -r requirements.txt
103+
or
104+
pip install -r requirements.txt --break-system-packages
137105

138-
Replace:
139-
140-
- `path/to/uv` with the actual path to your `uv` executable
141-
- `path/to/jadx-mcp-server` with the absolute path to where you cloned this
142-
repository
143-
144-
Then, navigate code and interact via real-time code review prompts using the built-in integration.
145-
146-
## Give it a shot
147-
148-
1. Run jadx-gui and load any .apk file
149-
150-
![img_1.png](docs/assets/img_1.png)
151-
152-
2. Start claude - You must see hammer symbol
153-
154-
![img2.png](docs/assets/img2.png)
155-
156-
3. Click on the `hammer` symbol and you should you see somthing like following:
157-
158-
![img3.png](docs/assets/img3.png)
159-
160-
4. Run following prompt:
161-
```text
162-
fetch currently selected class and perform quick sast on it
106+
# The setup for zin-mcp-client is done.
163107
```
164-
![img4.png](docs/assets/img4.png)
165-
166-
5. Allow access when prompted:
167108

168-
![img_1.png](docs/assets/img5.png)
169-
170-
6. HACK!
171-
172-
![img_2.png](docs/assets/img6.png)
173-
174-
This plugin allows total control over the GUI and internal project model to support deeper LLM integration, including:
175-
176-
- Exporting selected class to MCP
177-
- Running automated Claude analysis
178-
- Receiving back suggestions inline
179-
180-
---
181-
182-
## Running on Local LLM Using Ollama and Custom MPC Client
183-
184-
!Coming Soon...
185-
186-
## Running on Local LLM using Ollama and Open Web UI
187-
188-
Current State Of Local LLM and MCPs:
189-
190-
Currently, proprietary API-based models like Anthropic’s Claude tend to be more proficient proficient at tool calling.
191-
192-
However, the open-source world is advancing rapidly! Models specifically fine-tuned on function calling datasets are becoming increasingly available through Ollama. Researching models tagged with `function calling` or `tool use` on platforms like Hugging Face or [checking discussions on communities like r/LocalLLaMA is key to finding capable local options.](https://www.reddit.com/r/LocalLLaMA/search/?q=Best+open+source+LLM+for+function+calling+mcp&cId=c72f65d2-d327-41b0-8e6d-73e889385cda&iId=795a5a92-245d-42d2-ae60-47dfff7dbef0)
193-
194-
Putting these aside, Here is a step by step guide on how to run the MCP server with Local LLM so you don't have to share your critical pentesting data with remote LLM Provider.
109+
## 🤖 2. Ollama Setup
195110

196111
<div align="center">
197112
  <a href="https://ollama.com">
@@ -208,11 +123,11 @@ If you are on linux you can directly run below command to install it:
208123

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

211-
For example, the llama 3.1 has capability to invoke the tool. However, during testing I was not able to invoke tool via llama.3.1 and so for this example I am using gemma3:4b [Again this whole setup is based on LLM Capabilities]
126+
For example, the llama 3.1 has capability to invoke the tool.
212127

213128
You can run it using following command:
214129

215-
> ollama run gemma3:4b
130+
> ollama run llama3.1:8b
216131

217132
[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.
218133

@@ -225,102 +140,129 @@ This will serve the ollama api on port 1134, you can confirm that it running usi
225140
> curl http://localhost:11434/ 18:54:00
226141
`Ollama is running`
227142

228-
4. Download and run Open Web UI: https://github.com/open-webui/open-webui
143+
```
229144

230-
Kindly visit the github repo of Open Web UI and run it as per your requirement, for quick start, I like to run following command to run it using docker:
145+
## ⚙️ 3. Config File Setup
231146

232-
> docker run -d --network=host -v open-webui:/app/backend/data -e OLLAMA_BASE_URL=http://127.0.0.1:11434 -e WEBUI_AUTH=False --name open-webui --restart always ghcr.io/open-webui/open-webui:main
147+
The config file is the MCP Server configuration file that tells zin mcp client how to start the MCP Servers.
233148

234-
After running above command head over to http://localhost:8080/ and you will be able to see Open Web UI screen as shown in Image below:
149+
It follows the same style as Claude's configuration file.
235150

151+
Below is the sample configuration file for Zin MCP Suite Servers:
152+
153+
```json
154+
{
155+
"mcpServers": {
156+
"jadx-mcp-server": {
157+
"command": "/path/to/uv",
158+
"args": [
159+
"--directory",
160+
"/path/to/jadx-mcp-server/",
161+
"run",
162+
"jadx_mcp_server.py"
163+
]
164+
},
165+
"apktool-mcp-server": {
166+
"command": "/path/to/uv",
167+
"args": [
168+
"--directory",
169+
"/path/to/apktool-mcp-server/",
170+
"run",
171+
"apktool_mcp_server.py"
172+
]
173+
},
174+
"browser-bruter-mcp-server": {
175+
"command": "/path/to/uv",
176+
"args": [
177+
"--directory",
178+
"/path/to/BrowserBruter/modules/mcp/",
179+
"run",
180+
"browser_bruter_mcp_server.py"
181+
]
182+
}
183+
}
184+
}
236185
```
237-
<div align="center">
238-
  <a href="https://ollama.com">
239-
<img alt="ollama" src="https://github.com/user-attachments/assets/7c520551-e178-41d3-afd2-903b11b68bda">
240-
</a>
241-
</div>
242186

243-
If you don't see the gemma:3.4B as shown in image above, check the troubleshooting guide from Open Web UI: https://docs.openwebui.com/troubleshooting/
187+
Replace:
244188

245-
You must also observe the hammer icon indicating the availability of the tool.
189+
- `path/to/uv` with the actual path to your `uv` executable
190+
- `path/to/jadx-mcp-server` with the absolute path to where you have stored the jadx-mcp-server
246191

247-
![image](https://github.com/user-attachments/assets/3aaa9be0-050a-494e-8108-46222f1dbb3f)
192+
> [!NOTE]
193+
>
194+
> The default location of config file is inside zin-mcp-client directory named `mcp-config.json`, however you can provide path to your own config file using `--config` option such as
248195
249-
If not avaiable, then got `Settings -> Admin Panel -> Settings -> Tools` and verify the URL of the MCP Server.
196+
```bash
197+
uv run zin_mcp_client.py --server jadx-mcp-server --model llama3.1:8b --config /home/zinjacoder/mcp-config.json
198+
```
250199

251-
![image](https://github.com/user-attachments/assets/5c3d1e76-c7e0-412a-94c8-1be320489644)
200+
## Give it a shot
252201

253-
If everyhting is good, You must also see the traffic logs on MCP Server as well
202+
1. Run zin_mcp_client.py
254203

255-
![image](https://github.com/user-attachments/assets/9cf8da8e-c953-4b7c-954d-6c9607e91ad5)
204+
```bash
205+
uv run zin_mcp_client.py
206+
```
256207

257-
Now enter the prompt to invoke the MCP tool like following.
258208

259-
![image](https://github.com/user-attachments/assets/c557038d-2ba5-4983-9fb2-f912b1d0c21a)
260209

261-
The Local LLM based on it's capability must have invoked the MCP tool as shown in above image.
210+
2. Use `--server` option to specify server of your choice, use `--config` option to provide path to your config file, use `--model` option to use specific model, use `--debug` to enable verbose output
262211

263-
If not then again, Open Source LLMs are still catching up with tool inoking capabilities and soon we will have models with Strong tool calling capabilities.
212+
## If something went wrong - DEBUG and Troubleshooting
264213

265-
Aletrnative and better approach is to create a custom MCP Client to and use it with MCP Server.
214+
1. Look the logs:
266215

267-
## 🛣️ Future Roadmap
216+
- All the logs and debug information and raw traffic and interactions are stored in logs in easy to read way, If anything goes wrong check the logs.
268217

269-
- [x] Add Support for apktool
218+
2. Debug Mode:
270219

271-
- [ ] Add support for hermes code (ReactNative Application)
220+
- You can also use the `--debug` flag to enable debug to print each and every detail on console on runtime to help you find the issue.
272221

273-
- [ ] Add more useful MCP Tools
222+
https://github.com/user-attachments/assets/ee478917-c4f5-46fb-9f0e-ad31d7c33ee0
274223

275-
- [ ] Make LLM be able to modify code on JADX
224+
3. Open Issue:
276225

277-
- [ ] Add prompts templates, give llm access to Android APK Files as Resources
226+
- If you can not resolve the error on you own, use the logs and debug mode's output and provide them to us by opening an issue at https://github.com/zinja-coder/zin-mcp-client/issues
278227

279-
- [ ] Build MCP Client to support Local LLM
228+
---
280229

281-
- [ ] **END-GOAL** : Make all android reverse engineering and APK modification tools Connect with single MCP server to make reverse engineering apk files as easy as possible purely from vibes.
230+
## 🛣️ Future Roadmap
282231

232+
- [ ] Add Support HTTP based MCP Servers
283233

284-
## NOTE For Contributors
234+
- [ ] Add support exposing this client on network as well
285235

286-
- The files related to JADX-AI-MCP can be found under this repo.
236+
- [ ] Add more useful MCP Tools
287237

288-
- The files related to **jadx-mcp-server** can be found [here](https://github.com/zinja-coder/jadx-mcp-server).
238+
- [ ] **END-GOAL** : Make all reverse engineering MCP Servers, bring them together, to make reverse engineering as easy as possible purely from vibes.
289239

290240
## To report bugs, issues, feature suggestion, Performance issue, general question, Documentation issue.
291241
- Kindly open an issue with respective template.
292242

293-
- Tested on Claude Desktop Client, support for other AI will be tested soon!
243+
- Tested on Mac OS and Linux environment with Zin MCP Servers. (jadx-mcp-server, apktool-mcp-server)
294244

295245
## 🙏 Credits
296246

297-
This project is a plugin for JADX, an amazing open-source Android decompiler created and maintained by [@skylot](https://github.com/skylot). All core decompilation logic belongs to them. I have only extended it to support my MCP server with AI capabilities.
298-
299-
[📎 Original README (JADX)](https://github.com/skylot/jadx)
300-
301-
The original README.md from jadx is included here in this repository for reference and credit.
302-
303-
This MCP server is made possible by the extensibility of JADX-GUI and the amazing Android reverse engineering community.
304-
305-
Also huge thanks to [@aaddrick](https://github.com/aaddrick) for developing Claude desktop for Debian based linux.
247+
This project is a possible due to [ollama](https://ollama.com/), an amazing utility to rung local LLMs. The [langchain](https://www.langchain.com/) project,
306248

307-
And in last thanks to [@anthropics](https://github.com/anthropics) for developing the Model Context Protocol and [@FastMCP](https://github.com/modelcontextprotocol/python-sdk) team
249+
And in last thanks to [@anthropics](https://github.com/anthropics) for developing the Model Context Protocol and [@FastMCP](https://github.com/modelcontextprotocol/python-sdk) team.
308250

309251
Apart from this, huge thanks to all open source projects which serve as a dependencies for this project and which made this possible.
310252

311253
## 📄 License
312254

313-
JADX-AI-MCP and all related projects inherits the Apache 2.0 License from the original JADX repository.
255+
ZIN MCP Client and all related projects inherits the Apache 2.0 License.
314256

315257
## ⚖️ Legal Warning
316258

317259
**Disclaimer**
318260

319-
The tools `jadx-ai-mcp` and `jadx_mcp_server` are intended strictly for educational, research, and ethical security assessment purposes. They are provided "as-is" without any warranties, expressed or implied. Users are solely responsible for ensuring that their use of these tools complies with all applicable laws, regulations, and ethical guidelines.
261+
The tools `zin-mcp-client` and `zin mcp suite` are intended strictly for educational, research, and ethical security assessment purposes. They are provided "as-is" without any warranties, expressed or implied. Users are solely responsible for ensuring that their use of these tools complies with all applicable laws, regulations, and ethical guidelines.
320262

321-
By using `jadx-ai-mcp` or `jadx_mcp_server`, you agree to use them only in environments you are authorized to test, such as applications you own or have explicit permission to analyze. Any misuse of these tools for unauthorized reverse engineering, infringement of intellectual property rights, or malicious activity is strictly prohibited.
263+
By using `zin-mcp-client` or `zin mcp suite`, you agree to use them only in environments you are authorized to test, such as applications you own or have explicit permission to analyze. Any misuse of these tools for unauthorized reverse engineering, infringement of intellectual property rights, or malicious activity is strictly prohibited.
322264

323-
The developers of `jadx-ai-mcp` and `jadx_mcp_server` shall not be held liable for any damage, data loss, legal consequences, or other consequences resulting from the use or misuse of these tools. Users assume full responsibility for their actions and any impact caused by their usage.
265+
The developers of `zin-mcp-client` and `zin mcp suite` shall not be held liable for any damage, data loss, legal consequences, or other consequences resulting from the use or misuse of these tools. Users assume full responsibility for their actions and any impact caused by their usage.
324266

325267
Use responsibly. Respect intellectual property. Follow ethical hacking practices.
326268

@@ -329,10 +271,10 @@ Use responsibly. Respect intellectual property. Follow ethical hacking practices
329271
## 🙌 Contribute or Support
330272

331273
- Found it useful? Give it a ⭐️
332-
- Got ideas? Open an [issue](https://github.com/zinja-coder/jadx-ai-mcp/issues) or submit a PR
274+
- Got ideas? Open an [issue](https://github.com/zinja-coder/zin-mcp-client/issues) or submit a PR
333275
- Built something on top? DM me or mention me — I’ll add it to the README!
334276
- Do you like my work and keep it going? Sponsor this project.
335277

336278
---
337279

338-
Built with ❤️ for the reverse engineering and AI communities.
280+
Built with ❤️ for the reverse engineering and AI communities and all the awesome hackers and open source contributors around the world.

0 commit comments

Comments
 (0)