llm4s 0.1.13

K9s-inspired observability control tower for LLM & MCP Servers

llm4s (MCP-Lens)

K9s-inspired MCP traffic monitor for Claude Desktop

Claude Desktop이 MCP 서버를 호출할 때의 tool call 트래픽을 실시간으로 모니터링하는 터미널 UI 도구입니다.

---

MCP가 뭔지 모르겠다면

Claude Desktop은 두 가지 방식으로 통신합니다:

┌─────────────────────────────────────────────────────┐
│                  Claude Desktop                      │
│                                                      │
│   사용자가 채팅 입력                                  │
│       ↓                                             │
│   Claude (LLM) 가 판단                               │
│   "파일 읽기 도구 써야겠다"                            │
└──────────────┬──────────────────────────────────────┘
               │  JSON-RPC (stdio)
               │  {"method": "tools/call",
               │   "params": {"name": "read_file", ...}}
               ↓
┌─────────────────────────────────────────────────────┐
│              MCP 서버 (별도 프로세스)                  │
│                                                      │
│   예) filesystem 서버, fetch 서버, 직접 만든 서버 등   │
│                                                      │
│   실제로 파일 읽기 / 웹 요청 등 실행 후 결과 반환        │
└─────────────────────────────────────────────────────┘

• Claude ↔ Anthropic API: LLM 추론 (HTTPS, 볼 수 없음)
• Claude ↔ MCP 서버: tool call (stdio, llm4s가 모니터링)

llm4s는 Claude Desktop이 MCP 서버를 호출하는 순간을 포착합니다.

---

llm4s가 끼면

┌──────────────────┐
│  Claude Desktop  │
└────────┬─────────┘
         │ stdio (JSON-RPC)
         ↓
┌──────────────────┐
│   llm4s proxy    │  ← 트래픽을 가로채어 SQLite에 기록
└────────┬─────────┘
         │ stdio (JSON-RPC, 그대로 전달)
         ↓
┌──────────────────┐
│    MCP 서버       │  ← 정상 동작, 지연 없음
└──────────────────┘

┌──────────────────┐
│   llm4s TUI      │  ← DB 읽어서 실시간 표시
└──────────────────┘

핵심 설계: asyncio Queue + SQLite WAL — MCP 통신 속도에 영향 없음

---

빠른 시작

# 1. 설치
pipx install llm4s

# 2. 설정 (Claude Desktop 자동 연결 포함)
llm4s setup

# 3. Claude Desktop 재시작

# 4. 모니터링 시작
llm4s

llm4s setup 하나로 API key 등록 + Claude Desktop 자동 연결까지 완료됩니다.

---

MCP 서버 추가

# 서버 등록 → Claude Desktop 자동 연결까지 한 번에
llm4s add-server <이름> --command <명령어> -- <인자>

# 예시: filesystem 서버
llm4s add-server filesystem --command npx -- -y @modelcontextprotocol/server-filesystem ~/Desktop

---

TUI 화면 구성

3단계 계층 구조 (K9s 스타일):

단계	화면	내용
1	Providers	등록된 MCP 서버 목록
2	Sessions	대화 세션별 로그
3	Logs	tool call 상세 내용

로그 화면에서 볼 수 있는 것:

• 🔧 get_weather(location='Seoul') — 어떤 도구를 어떤 인자로 호출했는지
• ← 응답 결과 — MCP 서버가 반환한 내용
• 🔌 연결 요청 / ✓ 초기화 완료 등 MCP 연결 과정

키 바인딩

키	동작
Enter	다음 단계로 진입
Esc	이전 단계로 돌아가기
/	검색
e	페이로드 편집
r	편집한 메시지 재전송 (Replay)
x	세션 Markdown으로 내보내기
R / F5	새로고침
q	종료

고급 필터

method:tools/call     # 특정 메서드만 보기
dir:C2S               # 방향 필터 (C2S / S2C)
ms>3000               # 응답시간 3초 초과
error:true            # 에러만 보기

---

CLI 명령어

llm4s                  # TUI 대시보드 실행
llm4s setup            # 초기 설정 (API key + Claude Desktop 연결)
llm4s add-server ...   # MCP 서버 등록
llm4s list-servers     # 등록된 서버 목록
llm4s doctor           # 상태 점검

---

기술 스택

구성요소	기술
TUI	Textual
DB	SQLite WAL + aiosqlite
API	FastAPI
코어	Python asyncio

---

License

MIT