ChessAgine MCP: Bringing Chess Intelligence to Claude

Hey all, I'm back to share something I've been working on that bridges two worlds I'm passionate about: chess and AI tooling. It's called ChessAgine MCP, and it's now available as a Claude extension that transforms how you can interact with chess positions, games, and analysis directly in your Claude conversations.
Before I dive in, let me be honest about what this is and isn't. This isn't some revolutionary AI that plays grandmaster-level chess. It's a tool I built because I wanted to analyze chess positions, review games, and explore variations without constantly switching between Claude, my browser, and chess GUIs. Though I built ChessAgine GUI to do this on the web, the website lacks many of the great features Claude provides, and with this extension, ChessAgine can run tools on your own local laptop, and it helps convert Claude into a chess-aware ChessAgine!

If you are not sure what ChessAgine is, it stands for Chess Agent + Engine. You can read my initial blog post about what ChessAgine is and what it does to understand this blog post better!

What is ChessAgine MCP?

ChessAgine MCP is a Model Context Protocol server that gives Claude native chess capabilities. When you install it, Claude (LLM) gains access to a comprehensive suite of chess tools, everything from fetching Lichess games and analyzing positions with Stockfish to exploring opening databases and solving tactical puzzles and much more!
In practical terms, this means you can paste a FEN, ask Claude to analyze it, and Claude will actually fetch engine lines, evaluate the position thematically (material, mobility, king safety, etc.), and explain the critical ideas. You can drop a Lichess game URL and get a detailed review with critical moments highlighted. You can even work through puzzles interactively.
The key difference from just chatting with Claude about chess? Claude now has tools. It can query Stockfish, fetch real game data from Lichess, access opening statistics, explain chess positions via theme analysis, and visualize positions. It's not just guessing about chess anymore; with ChessAgine MCP, it now has the bridge to understand a chess position better and get enough context to answer chess queries correctly.

(A very high-level overview of ChessAgine MCP, think of it as a gateway into chess tools, LLM get access to)

My Journey Building This

I'll be honest: this started as a weekend hack that spiralled into months of work.
The origin story is pretty mundane. I was analyzing a complicated middlegame position and found myself constantly alt-tabbing between Claude (where I was trying to understand the strategic ideas), Lichess (to check the engine), and my local chess GUI (to play out variations). I thought, "Why can't Claude just do this stuff?"
Then I had this realization. I had already built ChessAgine as an open-source chess GUI website with plug-and-play integration where AI models act as chess buddies with access to engines and databases. But there was a problem. Running the website meant API costs. Every analysis request, every game review, every puzzle session was hitting OpenAI or Anthropic's APIs. For serious chess study, those costs add up fast. While most users were able to set up the API key on their ChessAgine GUI many struggled to do so, and even after I added ChessAgine Cloud models, where the website has small to medium models running to analyze the positions, the output analysis was not as good as larger reasoning models due to not properly using CoT (Chain of thought prompting).
I started thinking: what if I could bring that same chess intelligence directly into a user's laptop, but make it truly free to use? That is when I started thinking about creating a beta MCP server where the tools run locally on your machine. No API calls for the chess logic. No per-request costs. You can already use Claude desktop for free on your laptop, so why not make the chess analysis part completely free, running on your laptop?

So I started building the MCP server. First tool: fetch a Lichess game given a URL. Then I added Stockfish analysis. Then opening statistics. Then, tactical puzzle solving. Then theme-based position evaluation. This was the fun part, building heuristics for mobility, space, king safety, and other positional and tactical factors. Then game review with critical moment detection. Then batch analysis. The list kept growing.
The biggest technical challenge wasn't the chess logic. It was making the tools useful within a conversational interface. Claude is a language model, not a chess GUI. To solve this, I started breaking down the MCP tools and prompts into smaller units of work. For example is-legal-move tool just validates whether whatever Claude is trying to think about in a chess position is even legal. By breaking down these tools into smaller work functions, I was able to give Claude a handful of more than 25 tools to use based on his best judgment. Claude is agentic by nature, and it can very successfully comprehend the tool usage via the MCP protocol and smartly call tools after tools to perform an analysis.

I also spent a lot of time on the "chess intelligence" layer. Raw Stockfish output is powerful but often inscrutable to humans. Seeing "+1.2 after Nf3" doesn't tell you why Nf3 is good. So I built a position thematic analysis graph (PTAG) layer that breaks down positions by thematic elements. Claude can now say things like "White has a significant space advantage and better piece mobility, but Black's king is safer," using PTAG as a tool which gives a better overview than just reading raw engine eval numbers. The calculations and logic behind PTAG is another blog post itself, but in a quick summary, it creates a non-centipawn-based eval where a positive value means good for white, a negative value means good for black and zero is equal. The theme scores depend on that theme feature, for example, a +2 value of light squares means white has 2 light squares control, black with -3 of positional means white is doing worse on pawn structure, it's quite a deep topic, so I can talk about it in my future blog posts!

Coming back to the MCP work, the integration itself was surprisingly smooth. Anthropic's documentation is solid, and the protocol is well-designed. Most of my time went into the chess tools themselves, not the MCP plumbing. What excites me most is that this proves the concept: you can have sophisticated, AI-powered chess analysis without the per-request costs of API calls. The chess computation is local, the Stockfish WASM engine runs on cloud servers, and Claude just orchestrates it all locally on your laptop via the Claude desktop app.

(A visual representation of position theme analysis graphed on ChessAgine website, PTAG is under work but it does magic when given to Claude)

Seeing it in action!

Some of the use cases of chessAgine MCP include
- generating dashboards for game reviews
- analyzing stockfish lines with Claude
- analyzing a position with ChessAgine tools and Claude
- giving Claude access to the Lichess master database for opening analysis in text
- getting HTML code for chessboard and game navigation
- generating puzzle packs for students from the Lichess puzzle database
- doing interactive Lichess puzzles in Claude, asking for hints for puzzles or getting a quick analysis in text
- fetch your own Lichess studies and give Claude the ability to explain positions in the Lichess study

the use cases are endless, chess devs, students, and coaches can all use the Claude desktop extension and use the powers of LLM + chess for many tasks!

below are some screenshots of the above use cases.

Doing Interactive Puzzles

(Claude can fetch a hard puzzle for me and show the board using the HTML tool and fetch-puzzle-tool)

Of course! Let me give you some hints to guide you:
Hint 1 - Look at Black's King: The black king on h7 looks very vulnerable and exposed. It has limited escape squares.
Hint 2 - Your Active Pieces: Your knight on e4 is very well placed and can jump to some interesting squares. Also, notice your queen on c2 and rook on d6 are both active pieces that could coordinate in an attack.
Hint 3 - Sacrificial Ideas: Sometimes in tactical puzzles, especially with an exposed king, you need to consider forcing moves - even if they involve giving up material temporarily. What if your knight could move with a check or a strong threat?
Hint 4 - The Knight Jump: Look at where your knight on e4 can move. Is there a square where it attacks something important while also threatening the king or opening up new attacking lines?
Try looking at knight moves from e4 - especially ones that create immediate threats! What do you see?
- Claude + ChessAgine on showing me hints to the above puzzle

Generating Game dashboards

(Claude can talk to agine to get the PTAG graph over game moves and find themes, and generate UI dashboards! This dashboard covers Gukesh's loss against Svane. The dashboard can be found here)

Comparing Stockfish variations in words

(Claude + chessagine can call the Stockfish and provide possible explanations for Stockfish lines)

I'll analyze this position and compare Stockfish variations for you. Let me first show you the board and then get the analysis. Now let me get a multi-line Stockfish analysis to compare the best variations: Great! Here's a comparison of the top 5 Stockfish variations from this position:

## Position Analysis

This is the Italian Game after 1.e4 e6 2.Nf3 d5 3.Bc4. Black has just played ...c5, creating central tension.

## Top 5 Variations Compared:

1. exd5 exd5 Bb5+ Nc6 d4 Nf6 (Eval: +0.09)

• Best move - White takes on d5, forcing a trade
• Leads to an open center with roughly equal chances
• Bb5+ developing with tempo before Black can solidify
• Results in a slightly better position for White

2. Bb5+ Bd7 Bxd7+ Qxd7 exd5 Qxd5 (Eval: -0.04)

• Checking immediately and forcing trades
• Leads to a simplified position
• Nearly equal, very slightly favoring Black
• Good practical choice if seeking a draw

3. Bd3 dxe4 Bxe4 Nf6 Bd3 Nc6 (Eval: -0.59)

• Bishop retreats, allowing Black to capture
• Black gets comfortable development
• White is somewhat worse after this passive approach

4. Be2 dxe4 Ne5 Qc7 d4 Nf6 (Eval: -1.30)

• Bishop retreats too passively
• White struggles to justify the early loss of the center
• Black gets a comfortable advantage

5. Bf1 dxe4 Ne5 Qc7 Bb5+ Nd7 (Eval: -1.44)

• Worst option - retreating the bishop all the way back
• White has wasted time and loses central control
• Black gets a clear advantage

Recommendation

Play exd5! - This is clearly the best move, maintaining White's opening advantage and keeping the position dynamic. The alternatives that retreat the bishop are too passive and allow Black to seize the initiative.
Claude + ChessAgine using MCP tools to compare variations

Installing The Extension

This extension is 100% FREE TO USE. Installing ChessAgine MCP is straightforward, though you'll need the Claude Desktop app. It doesn't work in the web interface because MCP servers run locally.

Option 1: Using MCPB File (Recommended)

Download the chessagine-mcp.mcpb file and install it directly in Claude Desktop:

1. Download the latest release from GitHub releases at https://github.com/jalpp/chessagine-mcp/releases
2. Open Claude Desktop
3. Go to Settings, then Extensions, then Install from file
4. Select the chessagine-mcp.mcpb file
5. Restart Claude Desktop

This is the easiest method if you want a one-click installation without any command-line work.

Option 2: Local Development Setup

If you want to contribute or modify the code, you'll need Node.js 22+ and npm or yarn package manager.
Clone and setup:

git clone https://github.com/jalpp/chessagine-mcp.git
cd chessagine-mcp
npm install
npm run build:mcp

Then configure Claude Desktop by adding to your claude_desktop_config.json file.
For macOS and Linux:

{
  "mcpServers": {
    "chessagine-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/chessagine-mcp/build/runner/stdio.js"]
    }
  }
}

For Windows:

{
  "mcpServers": {
    "chessagine-mcp": {
      "command": "node", 
      "args": ["C:\\absolute\\path\\to\\chessagine-mcp\\build\\runner\\stdio.js"]
    }
  }
}

Once installed, you can verify it's working by asking Claude something like "Fetch my recent Lichess games" with your username, or "Analyze this position" with a FEN. If Claude can respond with actual data, you're good to go.
Most features work without authentication, but if you want to access private studies or have higher rate limits, you can set a Lichess API token in your MCP configuration by adding an env section with LICHESS_API_TOKEN

What's Next?

I'm treating this as a beta release. The core tools work well, but there's room for improvement. Better visualization options (currently using HTML artifacts but I want to explore more interactive formats). Support for more chess engines beyond Stockfish. Performance optimizations for batch analysis. More thematic evaluation dimensions.
The codebase is fully open source on GitHub and is licensed under MIT, and I'm happy to review PRs if any devs want to contribute to this project. My priority is keeping the tools reliable and useful rather than adding features for the sake of it.

I have also made a ton of updates to the web version of ChessAgine here, where I added FREE Ollama models support, and other things. I recorded a demo you can watch for the site below.

https://youtu.be/PCwVbNRFUW0?si=mhYHTq9UvlK2np40

Honest Thoughts

Let me be clear here, ChessAgine MCP is not the first of its kind; many have built chess MCPs, and those can easily be found on the internet. My MCP and the extension I built focus on fixing the chess context by implementing Chess Context Protocol into MCP tools, so the explanations and chain of thought LLMs follow is more clearer and better aligned to user queries. I also want to note I'm NOT just supplying LLMs with a bunch of "templates" that have reasoning steps, no, I tried that about 1.5 years ago, and I knew how stupid that was. This extension and MCP really give LLMs the tools to reason and understand chess queries. This can be clearly seen in how Claude gave me a hint for that puzzle; nowhere in the query did I tell Claude anything about a knight on e4. Claude was able to figure it out via the tools call. I also want to mention Claude + ChessAgine MCP is just a chess tool like how you use Stockfish, this tool makes our life simple, no way its near the intelligence of a chess grandmaster, and I didn't design it this way, I'm just trying to make LLMs chess-aware, not the next AI coach, many others are working on that, and good for them, this project is just me fixing the context layer, not the LLM itself!

(Fixing the bridge to the LLM, not the LLM itself)

Final Thoughts

ChessAgine MCP makes Claude genuinely useful for chess analysis and learning by giving it access to real tools and data. No more "Claude, what does the engine say here?" followed by Claude making up a plausible-sounding but wrong analysis.
If you analyze chess games, study openings, or just enjoy exploring positions, give it a try. It's free, open source, and works entirely locally. Your games and positions stay on your machine. And unlike many AI chess tools, the actual chess analysis doesn't cost you anything when using Claude's free tier. I developed the entire extension while being in the free tier and spending $0 on anything!
If you run into issues or have ideas, feel free to reach out on the community Discord. I built this for myself, but I'm excited to see how others use it.

Thanks for reading!

Noob