legal-skills-mcp

An MCP server that lets an AI assistant search open legal skills by keyword, by meaning, or both.

legal-skills-mcp connects an assistant such as Claude to legal-skills-open, a library of 20,293 legal skills in SKILL.md format, so that the assistant can work from the templates, procedures and checklists that already exist for a task.

Table of contents

• Overview

• Features

• How it works

• Search modes

• Skills

• The library at a glance

• Quick start

• Usage

• Results

• Memory

• Limitations

• Configuration

• Development

• Security and privacy

• Roadmap

• Contributing

• License and third-party licenses

• Acknowledgements

Related MCP server: skill-router-mcp

Overview

The Model Context Protocol (MCP) lets an assistant call tools that run outside it. legal-skills-mcp is one such server: it runs as a local process and talks to the MCP client, such as Claude Code, over stdio. The library it searches, legal-skills-open, is published by ThomasMoreAI. The server retrieves skills and drafts nothing itself. The current version is 0.3.0.

It is meant for:

• Lawyers who want their assistant to start from written procedures for a given jurisdiction.

• Legal-tech teams that want to check what the library covers by country, practice area and language.

• Developers who need a local, read-only source of legal skills, or an example of hybrid keyword and semantic search.

It finds the skills closest to a request, even when they share no words with the query, and can limit the search to one jurisdiction, language, practice area or tag.

Features

• Three read-only MCP tools: search, full skill retrieval and facet counts.

• Keyword (BM25) search by default, plus semantic search and hybrid search, which interleaves the two.

• Filters for jurisdiction, language, practice area and tag, and presets, including method, which covers method skills in every language.

• Cross-language matching through a multilingual model and a hand-written glossary of 19 legal concepts.

• No request to an external service once the model is downloaded.

• Third-party text marked as untrusted, and bundled scripts never executed.

• A keyword index in SQLite, rebuilt when a skill file changes. Only the index stays in memory: skill texts are read from disk when they are requested.

How it works

flowchart TD
    library["legal-skills-open: SKILL.md files"]
    query["Query from the MCP client"]
    keyword["Keyword index: BM25, stored in data/"]
    vectors["Vector index: one vector per skill"]
    hybrid["Hybrid mode: interleaves both rankings"]
    results["Ranked skills, returned as untrusted text"]

    library -->|"indexed at startup"| keyword
    library -->|"npm run build:embeddings"| vectors
    query --> keyword
    query -->|"same embedding model, run in a helper process"| vectors
    keyword --> hybrid
    vectors --> hybrid
    hybrid --> results

The server keeps two indexes of the library.

The keyword index ranks skills with BM25, a standard formula for text search. Fields have different weights: title 3, name and tags 2, description 2, and the first 6,000 characters of the body 1. Accents are ignored, and German umlauts match in both spellings, so "Gebühren" also matches "Gebuehren". A hand-written glossary links 19 legal concepts across languages: a query with "réclamation" also looks for "complaint", "Beschwerde" and "reclamação", and these equivalents count for half. The index is stored in data/legal-skills.sqlite (about 125 MB) and rebuilt when a skill file changes size or modification time. Postings are read from that file for each query, with a page cache of 16 MB, and a skill's text is read from the library only when get_legal_skill asks for it.

The vector index holds one 384-dimension vector per skill, computed from its title, description and tags. A vector is a list of numbers that describes the meaning of a text. The model is intfloat/multilingual-e5-small in its 8-bit ONNX form (Xenova/multilingual-e5-small), run locally through transformers.js and ONNX Runtime. Each query goes through the same model and is compared with the stored vectors. npm run build:embeddings computes the vectors once and stores them in a 31 MB file, which is loaded on the first semantic or hybrid search. The model runs in a helper process that starts on that first search and exits after a minute without searches, so its memory goes back to the system.

Hybrid mode takes the best keyword result and the best semantic result in turn, and skips duplicates. When keyword search finds a match, its best result ranks first and the best semantic result second.

Search modes

Skills

In this project, a skill is a set of written instructions for one legal task, such as writing a consumer complaint letter or reviewing an employment contract. Each skill is a Markdown file named SKILL.md: a YAML frontmatter header with metadata, then the text that guides the assistant through the task. Some skills also come with supporting files, scripts included.

The library groups skills by country, then by practice area:

{country}/{practice}/skills/{slug}/SKILL.md

A skill's id follows the same pattern, for example fr/contracts/skills/<slug>. The main frontmatter fields are:

The server never executes scripts bundled with a skill; get_legal_skill only lists them.

The library at a glance

Coverage by language is very uneven:

Quick start

You need Node.js 22 or later and Git.

git clone --recurse-submodules https://github.com/T-Celor/legal-skills-mcp.git
cd legal-skills-mcp
npm install
npm run build
npm run build:embeddings

The --recurse-submodules flag also fetches legal-skills-open, which the server reads from vendor/legal-skills-open by default.

In Claude Code, open the project folder. The .mcp.json file at its root declares the server as legal-skills, started with node --max-semi-space-size=1 dist/index.js, and Claude Code asks you to approve it the first time. Check the connection with:

claude mcp list

legal-skills should appear as connected. Other MCP clients can start the same command from the repository folder. The flag keeps memory low (see Memory).

The keyword index is built the first time the server starts, which takes about three minutes. npm run build:index builds it ahead of time.

Usage

The server exposes three tools, all read-only:

An assistant can start with list_legal_facets to see what exists for a language or jurisdiction, search with search_legal_skills, then read one result with get_legal_skill. Filter values are lowercase, such as fr, zh or employment, and list_legal_facets shows the values in use.

Example arguments for search_legal_skills:

{
  "query": "rupture du contrat de travail par l'employeur",
  "jurisdiction": "fr",
  "language": "fr",
  "limit": 4,
  "mode": "hybrid"
}

Choosing filters

Filters combine with AND, so each filter you add narrows the results. Explicit filters override the values a preset sets. Call list_legal_facets with the same explicit filters to see how many skills remain.

• For a topic question in French, start with "language": "fr" (109 skills). Add "jurisdiction": "fr" (127 skills, or 65 when combined with French) only when the question concerns France.

• For a method question, in any language, use "preset": "method". It selects the general practice area: 2,165 skills in every country and language, such as research methods, workflows and quality checks. Leave practice empty for topic searches.

• The preset "french-general" sets "jurisdiction": "fr", "practice": "general" and "language": "fr". It matches 12 French method skills, and it leaves out skills whose jurisdiction is general, such as Complaint Letter Writer, the top result for "réclamation consommateur". Use it when you need French method skills specifically.

Results

Four of the six queries tested are shown. Each was run in keyword mode and in hybrid mode on the full library, and the top 4 results were compared.

Across all six queries tested, hybrid mode never lowered the first result and improved the top 4 for three of them.

Method search in any language

With the method preset, a question about method finds method skills whatever language it is written in. Each query below was run with "preset": "method" and "mode": "hybrid".

Measured on Windows 11 with the full library, in one session:

Memory

The server keeps the index in memory, not the skill texts. Figures are the private memory of each process, measured on Windows 11 with the full library:

The helper exits after a minute without semantic searches, and the server then returns to its keyword figure. The start command passes --max-semi-space-size=1 to Node. Without that option, V8 kept roughly 120 MB of heap reserved after indexing, and the server measured about 285 MB.

Limitations

• The embedding model is light and sometimes returns off-topic results for vague queries.

• Tags cover about 3.6% of the library, so the tag filter is partial.

• French is under-represented, with 109 skills. For French questions, start with the language filter (see Choosing filters).

• The German query on bank fees stays weak, even in hybrid mode.

• The glossary is written by hand and does not cover all of law.

• Building the index takes about three minutes on first start or after the library changes. A client with a 60-second timeout may report an error on that first call. The build continues on the server, so a retry works once it is ready.

• Results are not legal advice, and the project does not guarantee the legal quality of third-party skills.

Configuration

The server reads two optional environment variables:

The start command, in package.json and .mcp.json, passes --max-semi-space-size=1 to Node. See Memory.

Development

The server is written in TypeScript. Its main dependencies are @modelcontextprotocol/sdk, @huggingface/transformers, yaml and zod.

Project layout:

src/index.ts             stdio entry point
src/server.ts            the three tools
src/store.ts             SQLite index: keyword ranking, facets, skill reads
src/catalog.ts           finding, indexing and fingerprinting SKILL.md files
src/glossary.ts          cross-language concepts
src/text.ts              tokenisation
src/semantic.ts          vectors, similarity, interleaving
src/embedder.ts          the transformers.js model, and the helper process that runs it
src/embed-protocol.ts    requests and replies between the server and the helper
src/embed-worker.ts      the helper process
src/build-index.ts       builds the keyword index
src/build-embeddings.ts  builds the vector index
src/labels.ts            language names

To run the tests:

npm test

The 75 automated tests cover indexing, the SQLite index and its rebuilds, the glossary, the MCP protocol, the stdio entry point, hybrid search, the embedding helper and filter presets. They also use the real library when the submodule is present.

Security and privacy

• Once the model is downloaded, the server sends no request to an external service.

• Results reach the assistant's model like any other tool output.

• Third-party skill text is returned marked as untrusted, inside a random boundary that changes with each response.

• Bundled scripts are never executed.

• Symbolic links are never followed, and YAML aliases are refused.

• Skill ids are looked up in an index and never used as file paths.

Roadmap

Ideas for later versions, open to discussion:

• Try a larger multilingual embedding model, or one trained on legal text, to reduce off-topic results.

• Reduce the helper's memory, which is the largest part of the footprint while semantic search runs.

• Extend the glossary beyond its 19 concepts, starting with weak topics such as bank fees.

• Build a larger set of test queries with expected results, so that ranking changes can be measured.

• Propose tags for untagged skills to legal-skills-open, so that the tag filter covers more of the library.

Contributing

Bug reports and pull requests are welcome on GitHub. Please run npm run typecheck and npm test before opening a pull request. Changes to the skills themselves belong in legal-skills-open.

License and third-party licenses

Check a skill's license before you redistribute it.

Acknowledgements

• ThomasMoreAI for legal-skills-open.

• intfloat for multilingual-e5-small, and Xenova for its ONNX conversion.

• The maintainers of the MCP TypeScript SDK, transformers.js, ONNX Runtime, yaml and zod.