Content
<a id="readme-top"></a>
<div align="center">
[![Python][python-shield]][python-url]
[![FastAPI][fastapi-shield]][fastapi-url]
[![MCP][mcp-shield]][mcp-url]
[![LangChain][langchain-shield]][langchain-url]
[![Playwright][playwright-shield]][playwright-url]
[![Ollama][ollama-shield]][ollama-url]
[![License][license-shield]][license-url]
</div>
<br />
<div align="center">
<h3 align="center">Hanime1 MCP</h3>
<p align="center">
Hanime1 Resource MCP/Agent for AI programming assistants.
<br />
Supports natural language search, candidate confirmation, video parsing, download queue, breakpoint continuation, persistent recording, and vector memory.
<br />
<br />
<a href="#using-with-claude-code"><strong>Claude Code Integration</strong></a>
·
<a href="#using-with-cursor--trae--opencode">Cursor / Trae / opencode</a>
·
<a href="#mcp-tools">MCP Tools</a>
</p>
</div>
## Main Capabilities
- MCP Server: Can be integrated with Claude Code, Cursor, Trae, opencode, and other MCP-supported programming assistants.
- LangChain Agent: Uses Ollama local models for structured intent parsing and candidate ranking.
- Search and Parsing: Site search, classification/sorting search, and video source parsing on playback pages.
- Download Queue: Concurrent downloads, `.part` breakpoint continuation, and automatic saving as `.mp4` after completion.
- Local Memory: SQLite saves resources, tasks, and events; vector indexes are used for historical semantic retrieval.
## Environment Preparation
Required:
- Python 3.10+
- [uv](https://docs.astral.sh/uv/)
- [Ollama](https://ollama.com/)
Install dependencies:
```powershell
cd F:\MyProject\AI-Mcp\hanime\hanime-agent
uv sync --extra all
uv run playwright install chromium
```
Prepare local models:
```powershell
ollama pull qwen3:1.7b
ollama pull nomic-embed-text
```
Copy configuration:
```powershell
Copy-Item .env.example .env
```
Default configuration usage:
```env
HANIME_AGENT_LLM_PROVIDER=ollama
HANIME_AGENT_LLM_MODEL=qwen3:1.7b
HANIME_AGENT_EMBEDDING_MODEL=ollama:nomic-embed-text
HANIME_AGENT_OLLAMA_BASE_URL=http://127.0.0.1:11434
```
## Using with Claude Code
Remove old configuration and add new MCP:
```powershell
claude mcp remove hanime-agent
claude mcp add -s user -t stdio hanime-agent "F:\MyProject\AI-Mcp\hanime\hanime-agent\run-mcp.cmd"
```
Check:
```powershell
claude mcp list
claude mcp get hanime-agent
```
Enter Claude Code and input:
```text
/mcp
```
Confirm `hanime-agent` is connected and make natural language calls:
```text
Use hanime-agent to help me find resources related to "告白…… 1", list candidates for me to confirm.
```
Confirm download:
```text
Download the first one in 1080p.
```
You can also explicitly specify MCP tools:
```text
Call hanime-agent's chat_hanime_agent with the message "Help me find recent 3DCG resources, list the top 8".
```
## Using with Cursor / Trae / opencode
Add the following MCP configuration to the client's MCP configuration file:
```json
{
"mcpServers": {
"hanime-agent": {
"command": "F:/MyProject/AI-Mcp/hanime/hanime-agent/run-mcp.cmd"
}
}
}
```
If the client does not accept `.cmd` as a command, use:
```json
{
"mcpServers": {
"hanime-agent": {
"command": "uv",
"args": ["run", "--extra", "mcp", "--extra", "langchain", "hanime-agent", "mcp"],
"cwd": "F:/MyProject/AI-Mcp/hanime/hanime-agent"
}
}
}
```
## MCP Tools
- `chat_hanime_agent`: Main entrance, multi-round natural language search, candidate confirmation, and download.
- `search_hanime`: Directly search for resources.
- `inspect_hanime_video`: Parse a single playback page.
- `download_hanime_video`: Directly create a download task.
- `semantic_history_search`: Search local vectorized historical records.
## Local Debugging
Start MCP Server:
```powershell
.\run-mcp.cmd
```
Start FastAPI:
```powershell
uv run hanime-agent serve-api
```
CLI example:
```powershell
uv run hanime-agent ask "Help me find MMD recent resources, list the top 5"
uv run hanime-agent download "https://hanime1.me/watch?v=406271" --resolution 1080p
```
Run tests:
```powershell
uv run --extra dev pytest -q
uv run --extra dev ruff check .
```
## License
MIT License, see [LICENSE](LICENSE) for details.
## Disclaimer
This project is for technical learning and personal automation research only. Please comply with the target site's terms, copyright requirements, and local laws and regulations, and only download content you are entitled to save.
[python-shield]: https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white
[python-url]: https://www.python.org/
[fastapi-shield]: https://img.shields.io/badge/FastAPI-API-009688?logo=fastapi&logoColor=white
[fastapi-url]: https://fastapi.tiangolo.com/
[mcp-shield]: https://img.shields.io/badge/MCP-Server-111827
[mcp-url]: https://modelcontextprotocol.io/
[langchain-shield]: https://img.shields.io/badge/LangChain-Agent-1C3C3C
[langchain-url]: https://www.langchain.com/
[playwright-shield]: https://img.shields.io/badge/Playwright-Chromium-2EAD33?logo=playwright&logoColor=white
[playwright-url]: https://playwright.dev/python/
[ollama-shield]: https://img.shields.io/badge/Ollama-qwen3%3A1.7b-000000
[ollama-url]: https://ollama.com/
[license-shield]: https://img.shields.io/badge/License-MIT-green
[license-url]: LICENSE
