Skip to main content

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

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)

Source distribution for folio-mcp 0.4.5
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)

Table of built distributions (wheels) for folio-mcp 0.4.5
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page