folio-mcp
MCP server for FOLIO, the Federated Open Legal Information Ontology.
FOLIO is an open-source legal ontology with 18,000+ concepts covering areas of law, document types, legal entities, governmental bodies, and more. This MCP server makes the full ontology available to AI agents as searchable, browsable tools.
A public REST API is already available at https://folio.openlegalstandard.org/ with interactive Swagger documentation at /docs. This MCP server wraps the same ontology for native use in AI coding assistants and agent frameworks.
License: MIT (server code) / CC-BY 4.0 (ontology data)
Backends
folio-mcp supports two interchangeable backends:
| Mode | Startup | Dependencies | Use case |
|---|---|---|---|
| API (default) | Instant | httpx only |
Normal usage — calls the public FOLIO REST API |
Local (--local) |
~10s | folio-python[search] |
Offline use or when mounting inside folio-api |
API mode (default)
The server starts instantly and delegates all queries to the public API at https://folio.openlegalstandard.org/. No local ontology loading required.
Local mode
Loads the full FOLIO ontology in-process (~18k classes). Useful for offline work or when embedded in folio-api.
# Install with local dependencies
pip install folio-mcp[local]
# Run in local mode
folio-mcp --local
# Or via environment variable
FOLIO_MCP_LOCAL=1 folio-mcp
Custom API URL
Point to a different FOLIO API instance:
folio-mcp --api-url https://my-folio-instance.example.com
Installation
Claude Code
claude mcp add folio -- uvx folio-mcp
Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"folio": {
"command": "uvx",
"args": ["folio-mcp"]
}
}
}
Cursor
Add to .cursor/mcp.json in your project:
{
"mcpServers": {
"folio": {
"command": "uvx",
"args": ["folio-mcp"]
}
}
}
VS Code
Add to your User Settings (JSON):
{
"mcp": {
"servers": {
"folio": {
"command": "uvx",
"args": ["folio-mcp"]
}
}
}
}
Remote (Streamable HTTP)
Connect to the hosted endpoint:
https://folio.openlegalstandard.org/mcp
Manual (pip)
pip install folio-mcp
folio-mcp
Tools (13, plus 1 optional)
| Tool | Description |
|---|---|
search_concepts(query, limit=10) |
Search concepts by label/name using fuzzy matching (start here; max 50) |
search_definitions(query, limit=10) |
Loose fuzzy search over definition text (fallback) |
query_concepts(...) |
Advanced query with composable text and structural filters |
query_properties(...) |
Query OWL object properties by label, domain, range |
get_concept(iri) |
Get full details for a concept by IRI |
export_concept(iri, format) |
Export a concept as markdown, JSON-LD, or OWL XML |
list_branches() |
List all 24 taxonomy branches with concept counts |
get_taxonomy_branch(branch_name, max_depth) |
Get concepts in a taxonomy branch |
get_children(iri, max_depth) |
Get child concepts |
get_parents(iri, max_depth) |
Get parent concepts |
get_properties() |
List all OWL object properties (iri, label, short definition) |
find_connections(subject_iri, property_name, object_iri) |
Find semantic triples |
extract_concepts(text, limit=50, branch=None) |
Tag pasted text with the FOLIO concepts it mentions (label/synonym dictionary match; first call builds the index in ~1s) |
extract_citations(text, limit=100) |
Optional, needs the kaos extra on Python 3.13+. Find legal citations (cases, U.S.C., C.F.R., federal rules, ...) and map each to its FOLIO legal authority type and, for federal appellate/Supreme Court cases, the court |
extract_citations is registered only when kaos-citations is installed:
uvx --python 3.13 --from 'folio-mcp[kaos]' folio-mcp
Browse operations return compact summaries (iri, label, definition). Use get_concept(iri) for full details including translations (31% of concepts, 10+ languages), preferred labels, external identifiers, and cross-references.
Prompts (3)
| Prompt | Description | Argument |
|---|---|---|
classify-document |
Classify a legal document against the FOLIO taxonomy | description |
identify-area-of-law |
Identify applicable areas of law for a situation | situation |
classify-entity |
Classify a legal entity (person, org, role) | entity |
Each prompt guides the LLM through the correct tool workflow and returns structured output (FOLIO label, IRI, definition, confidence, reasoning).
Resources (3)
| Resource URI | Description |
|---|---|
folio://branches |
Branch names with concept counts (564 bytes) |
folio://stats |
Ontology statistics — version, class/property counts, license |
folio://branch/{name} |
Top-level concepts in a specific branch (on-demand) |
Taxonomy Branches
The FOLIO ontology is organized into 24 top-level branches:
| Branch | Description |
|---|---|
actors_players |
Parties, roles, and participants in legal matters |
areas_of_law |
Legal practice areas and specializations |
asset_types |
Types of assets (real property, intellectual property, etc.) |
communication_modalities |
Communication channels and methods |
currencies |
Monetary currencies |
data_formats |
Data and file formats |
document_artifacts |
Legal documents, contracts, filings |
engagement_terms |
Terms of engagement and fee arrangements |
events |
Legal events and milestones |
forum_venues |
Courts, tribunals, and dispute resolution venues |
governmental_bodies |
Government agencies and departments |
industries |
Industry sectors and classifications |
languages |
Natural languages |
folio_types |
FOLIO internal type classifications |
legal_authorities |
Statutes, regulations, case law |
legal_entities |
Entity types (corporations, LLCs, trusts, etc.) |
locations |
Geographic locations and jurisdictions |
matter_narratives |
Matter descriptions and narratives |
matter_narrative_formats |
Formats for matter narratives |
objectives |
Legal objectives and goals |
services |
Legal services and service types |
standards_compatibilities |
Standards and compatibility mappings |
statuses |
Status values for matters, documents, etc. |
system_identifiers |
System and external identifiers |
Development
# Clone and install
git clone https://github.com/alea-institute/folio-mcp.git
cd folio-mcp
uv sync
# Run tests (requires folio-python for local backend tests)
uv sync --extra local
uv run pytest tests/
# Run with MCP Inspector
uv run mcp dev folio_mcp/server.py
# Run locally for Claude Code
claude mcp add folio-dev -- uv run --directory /path/to/folio-mcp folio-mcp
Links
- FOLIO Website
- FOLIO REST API — public API for direct HTTP access
- FOLIO API Docs (Swagger) — interactive API documentation
- folio-python — Python client library
- folio-api — REST API server
- ALEA Institute
Metadata
Release files for folio-mcp 0.4.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| folio_mcp-0.4.5.tar.gz | 32.3 kB | Without provenance | Details for folio_mcp-0.4.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| folio_mcp-0.4.5-py3-none-any.whl | Python 3 | none | any | Details for folio_mcp-0.4.5-py3-none-any.whl |
Total release size: 70.1 kB
Release files / folio_mcp-0.4.5.tar.gz
| Download URL | folio_mcp-0.4.5.tar.gz |
|---|---|
| Size | 32.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bd0a54f430ae8c49a508a2363b4e3708c3a05581424163863737bfbfdbf45ba9
|
|
BLAKE2b-256 checksum How to use checksums |
f970d7229b831909002ca2fcf472ca02c7bf8f94d0087f113a4859ffd6dc5747
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.17
|
Release files / folio_mcp-0.4.5-py3-none-any.whl
| Download URL | folio_mcp-0.4.5-py3-none-any.whl |
|---|---|
| Size | 37.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9f5be2917e6714a0df9c6823fb0d8b40754353e077c45ec82e692e0b5248ee77
|
|
BLAKE2b-256 checksum How to use checksums |
da6af872c5cd8d1dd8ba1712ca271add2360e665be223a76ec1b1a37ef246f20
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.17
|
Security for folio-mcp 0.4.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.