bjjgraph
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bjjgraph how do I get from half guard bottom to back control?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
bjjgraph-mcp
A small local MCP server that lets Claude (Claude Code, Claude Desktop) look things up in BJJGraph — a directed graph of Brazilian Jiu-Jitsu positions (each with a top and bottom role), transitions, submissions, systems, principles and learning notes.
Ask things like "How do I get from half guard bottom to the back?" and Claude answers from the graph: routes, step-by-step execution, counters, common errors and defensive options.
This repository contains code only. It does not include BJJGraph data.
The code here is MIT-licensed (see LICENSE).
The BJJGraph data is © Diogo Seca and licensed under PolyForm Noncommercial 1.0.0. It is not included. Each user downloads it themselves with
npm run fetch-data, and may use it for noncommercial purposes only, under that licence's terms.Per its own README, BJJGraph content is produced with AI-assisted generation, and its probabilities are authored estimates that have not been validated by a panel of black belts. Treat it as a study aid, not ground truth.
This project is not affiliated with or endorsed by BJJGraph or its author.
Requirements
Node.js 20 or newer
About 45 MB of disk space for the downloaded data
Related MCP server: LLM Graph Builder MCP
Install
git clone https://github.com/hanwong/bjjgraph-mcp.git
cd bjjgraph-mcp
npm install # also builds the server into dist/
npm run fetch-data # downloads BJJGraph's content JSON into data/bjjgraph.jsonfetch-data downloads the BJJGraph repository archive from GitHub, keeps only content/**/*.json (positions, transitions, submissions, systems, principles, learning), and saves one bundle file in data/ (git-ignored). Downloaded files are only parsed as JSON — nothing from the download is extracted or executed. BJJGraph changes often; rerun npm run fetch-data any time to refresh. The server notices the new file automatically.
Options: npm run fetch-data -- --ref <branch-or-commit> and --out <file>. To use a BJJGraph checkout you already have, set BJJGRAPH_DATA to its folder (or to a bundle file).
Add to Claude Code
From inside the bjjgraph-mcp folder:
claude mcp add bjjgraph --scope user -- node "$(pwd)/dist/src/index.js"Then run claude mcp list to confirm it shows bjjgraph: ... ✓ Connected.
Add to Claude Desktop
Open Settings → Developer → Edit Config (this opens claude_desktop_config.json) and add the server, using the absolute path to your clone:
{
"mcpServers": {
"bjjgraph": {
"command": "node",
"args": ["/absolute/path/to/bjjgraph-mcp/dist/src/index.js"]
}
}
}Restart Claude Desktop.
Tools
Tool | What it does |
| Fuzzy search by name or alias across positions, transitions, submissions, systems, principles and learning notes. Partial names and typos work; common Korean terms (하프가드, 백, 암바…) are translated. |
| Full detail for a transition or submission: outcomes and probabilities, conditions, key principles, setup, execution steps, counters, common errors, training progressions, defender cues and options, variants, safety, clips. Filter with |
| A position for the top and/or bottom role: overview, properties and metrics, principles, decision tree, errors, drills, technique menu, clips. |
| What can be attempted from a position and role, most common first, with where each outcome leads. |
| A few shortest routes between two positions using only successful outcomes, with the techniques for each step. The goal can also be a submission (e.g. "Armbar"). |
| Lists systems, principles, learning notes, positions or submission families. |
| Full content of a system, principle or learning note. |
| Loaded data version (commit, date, counts), how to refresh, licence. |
Long results are paged (page, max_chars; default 6,000 characters) so they don't flood the conversation.
Roles. States are written Position/Role, from the point of view of whoever does the technique: Back Control/Top means you have the back; Half Guard/Bottom means you are playing half guard.
Example questions
"How do I get from half guard bottom to back control?"
"What can I do from closed guard bottom in no-gi?"
"Show me the execution steps and common errors for the Kimura Sweep."
"How do I defend the triangle? Give me the defender's recognition cues."
"Find a route from side control bottom to mount top."
"Which principles does BJJGraph list? Explain Pressure."
"What systems are there for half guard?"
Development
npm test # builds, then runs tests against a tiny made-up fixture (test/fixture)
npm run check-data # sanity checks every tool and entry against your downloaded data한국어 안내
Claude(Claude Code, Claude Desktop)가 BJJGraph의 주짓수 포지션·기술·서브미션·시스템·원리를 찾아볼 수 있게 해 주는 로컬 MCP 서버입니다. 예를 들어 "하프가드에서 백까지 가는 방법 알려줘"라고 물으면, 그래프에서 경로와 단계별 실행 방법, 카운터, 흔한 실수를 찾아 답합니다.
설치
git clone https://github.com/hanwong/bjjgraph-mcp.git
cd bjjgraph-mcp
npm install
npm run fetch-data
claude mcp add bjjgraph --scope user -- node "$(pwd)/dist/src/index.js"BJJGraph 데이터는 자주 갱신되니, 가끔 npm run fetch-data를 다시 실행하면 최신 데이터로 바뀝니다.
꼭 알아 두세요
이 저장소의 코드는 MIT 라이선스입니다.
BJJGraph 데이터는 © Diogo Seca, PolyForm Noncommercial 1.0.0 라이선스이며 이 저장소에 포함되어 있지 않습니다. 각자
npm run fetch-data로 내려받으며, 비상업적 용도로만 쓸 수 있습니다.BJJGraph 내용은 상당 부분 AI의 도움으로 만들어졌고, 확률은 작성자가 정한 추정치입니다(블랙벨트 검증 전). 공부 보조 자료로만 쓰고, 정답으로 받아들이지 마세요.
Available Tools
8 toolsbjj_aboutAbout the dataBRead-only
Which BJJGraph version is loaded (commit, fetch date, counts), how to refresh it, and the data licence.
Inputs: no named parameters.
bjj_find_pathsFind paths between positionsARead-only
Finds a few shortest routes from one position to another using only successful technique outcomes (e.g. Half Guard bottom → Back Control top). Each step lists the techniques that achieve it. The target may also be a submission (e.g. "Armbar"): routes then end at a position where it can be attempted.
Inputs: to (required), from (required), ruleset, to_role, +4 more.
bjj_get_conceptGet system, principle or learning noteARead-only
Full content of a system (game plan, with study guide and sources), a principle (component skills, decision framework, errors, training approaches) or a learning note.
Inputs: name (required), page, type, max_chars.
bjj_get_positionGet position detailBRead-only
Detail for one position, for the top and/or bottom role: overview, state properties and metrics, key principles, decision tree, common errors, drills, the technique menu with attempt weights, related positions and clips.
Inputs: name (required), page, role, sections, +1 more.
bjj_get_techniqueGet technique detailARead-only
Full detail for one transition or submission: outcomes and probabilities, conditions, key principles, setup, execution steps, common counters, common errors, training progressions, defender recognition cues / defensive options / escapes, variants, related content, safety and video clips. Use sections to fetch only what you need.
Inputs: name (required), page, sections, max_chars, +1 more.
bjj_listList BJJGraph entriesARead-only
Lists entries of one kind with a one-line summary: systems (game plans / courses), principles, learning notes, positions or submission families. Optional text filter.
Inputs: type (required), limit, filter, offset.
bjj_position_optionsWhat can I do from here?ARead-only
Lists the transitions and submissions that can be attempted from a position in a given role, most commonly attempted first, with success rate and where each outcome (success / failure / counter) leads.
Inputs: position (required), role, type, limit, +2 more.
bjj_searchSearch BJJGraphARead-only
Fuzzy search positions, transitions (sweeps, passes, escapes, takedowns…), submissions, systems, principles and learning notes by name or alias. Partial English names work; common Korean terms are translated.
Inputs: query (required), type, limit, offset.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a fairly distinct resource+action: search (fuzzy across all), list (enumerate one kind), get_technique/get_position/get_concept (detail per entity type), position_options (menu for a role), find_paths (routing), about (metadata). The closest pair is bjj_list vs bjj_search and bjj_position_options vs bjj_get_position, but the descriptions make the boundaries clear enough that an agent should pick correctly.
All tools share the bjj_ prefix and snake_case, with a mostly predictable verb-first pattern (search, list, get_technique, get_position, get_concept, find_paths) plus two noun-ish outliers (position_options, about). Minor deviation but highly readable.
Eight tools is well-scoped for a read-only knowledge graph: retrieval by search, enumeration, per-entity detail, position menus, pathfinding, and metadata. No obvious redundancy or missing bulk operations that would warrant extra tools.
The surface covers discovery (search/list), drill-down (get_technique/get_position/get_concept), role-based options, and navigation (find_paths), plus version metadata. Minor gaps like no explicit reverse lookup (e.g. techniques that end in a position) or bulk compare are workaroundable via search and find_paths.
Maintenance
Related MCP Connectors
BJJ gym, coach, event, and city data for AI agents. Free base tools, x402-paid premium.
BJJ video analysis — YOLO pose detection + Claude AI technique analysis.
Knowledge graph for AI agents. Query concepts, walk edges, get advisories.
BJJ video analysis — YOLO pose detection, AI technique analysis, and highlight reels.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables Claude to search, query, and interact with an Enterprise Knowledge Management System (EKMS). Supports semantic search, knowledge recommendations, relationship graphs, and feedback recording for enterprise knowledge bases.7MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to automatically extract entities and relationships from URLs, PDFs, and YouTube videos to build structured knowledge graphs in Neo4j. It supports custom schemas, academic citation extraction, and community detection for advanced research and content analysis.Apache 2.0
- FlicenseAqualityDmaintenanceAutomatically organizes and merges learned CS knowledge into a graph structure using Claude for entity/relation extraction and SQLite for storage, with tools for ingestion, querying, merging, and managing nodes and edges.6-
- FlicenseNot gradedqualityDmaintenanceEnables Claude to intelligently analyze and query codebases using knowledge graphs, supporting natural language code search, relationship discovery, and incremental updates.11-