langextract-mcp

langextract-mcp is an independent, standalone stdio MCP server that exposes Google LangExtract through three bounded tools:

• langextract_extract: model-assisted extraction from literal text, with source spans.

• langextract_visualize: return escaped interactive HTML for an annotated payload.

• langextract_status: safe configuration and limit report.

This is an independent wrapper. It is not affiliated with or supported by Google. It is not published to PyPI.

The server does not read caller files, fetch caller URLs, accept model URLs, accept credentials, or write output files. langextract_extract wraps text in a langextract.core.data.Document iterable and passes fetch_urls=False, including on LangExtract versions where URL-shaped strings could otherwise be significant.

Install and run from a clone

Requirements: Python 3.11+ and uv.

git clone https://github.com/CuriosityQuantified/langextract-mcp.git
cd /absolute/path/to/langextract-mcp
uv sync --frozen --all-groups
uv run --frozen langextract-mcp

No MCP client registration occurs automatically. For an MCP client that uses mcpServers, add a server entry manually:

{
  "mcpServers": {
    "langextract": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/langextract-mcp",
        "run",
        "--frozen",
        "langextract-mcp"
      ]
    }
  }
}

Related MCP server: Contract Information Extractor

Optional Git-installed launch

After the v0.1.0 tag exists, an MCP client can launch the tagged source directly with uvx:

uvx --from git+https://github.com/CuriosityQuantified/langextract-mcp@v0.1.0 langextract-mcp

This command installs from Git, not PyPI. It requires network access and does not replace a clone when you need the frozen repository lockfile for reproducible development or checks.

Hermes configuration

Add this to the appropriate Hermes profile, replacing the example path with your clone's absolute path:

mcp_servers:
  langextract:
    command: uv
    args: ["--directory", "/absolute/path/to/langextract-mcp", "run", "--frozen", "langextract-mcp"]
    timeout: 180
    sampling:
      enabled: true
      max_tokens_cap: 1024
      timeout: 120
      max_tool_rounds: 0

Use an absolute path to uv if your MCP host does not inherit your shell's PATH. Reload the MCP connection or start a fresh host session after configuration.

Inference providers

The default (LANGEXTRACT_MCP_PROVIDER=sampling) uses the MCP host's sampling capability. The host must implement MCP sampling (sampling/createMessage); this server asks for a single text response, no tools, no included context, and at most 1,024 generated tokens. This is the preferred mode because the server does not need a new API key.

An operator may instead set LANGEXTRACT_MCP_PROVIDER to gemini, openai, or ollama, and optionally LANGEXTRACT_MCP_MODEL. OpenAI mode requires the optional extra and a locked install:

uv sync --frozen --all-groups --extra openai

Credentials remain server environment only: LANGEXTRACT_API_KEY for Gemini and OPENAI_API_KEY for OpenAI. Ollama uses its default local endpoint; the tool never receives a URL or provider kwargs. Network providers can disclose submitted text to the configured provider and can charge for tokens. Extraction passes multiply inference cost; smaller character buffers can cause more calls. Direct provider calls use one worker, disable retries where supported, and set a 120-second request timeout. Direct inference checks cancellation and a 100-request/120-second budget before each new request. An already-blocking SDK request may still run until its request timeout; cancellation prevents later requests rather than forcibly terminating the SDK.

This project deliberately does not load .env files; set environment variables in the host process.

Grounding and visualization

grounded_only=true is the default. It removes model outputs LangExtract could not align to source text. A retained span may have match_exact, match_greater, match_lesser, or match_fuzzy; exact_match is computed by direct character comparison of extraction_text and source_substring. Every returned span includes source_substring, the literal substring at the reported character interval. Missing interval/status/substrings means the model output was not grounded and appears only when grounded_only=false.

Visualization accepts payload JSON, not paths. The wrapper bounds the payload before rendering and re-encodes the released renderer's embedded JSON with script-safe escaping; visible text, classes, and attributes are HTML-escaped. Treat returned HTML as display content, not trusted executable application code.

Extraction quality depends on the host model and examples. An empty extraction list is not proof that no relevant entities exist. Models may repeat few-shot examples; grounded_only removes outputs without a source span, not every possible semantic mistake. Review the actual source substring and exact_match flag for important uses.

Calling the extraction tool

{
  "text": "Grace Hopper visited London.",
  "prompt_description": "Extract people and cities using exact source text, in order of appearance.",
  "examples": [{
    "text": "Ada Lovelace visited Paris.",
    "extractions": [
      {"extraction_class": "person", "extraction_text": "Ada Lovelace"},
      {"extraction_class": "city", "extraction_text": "Paris"}
    ]
  }],
  "visualization": true
}

Pass the returned annotated document to langextract_visualize as annotated_document to render it separately. The HTML is returned as text; saving it is the client's choice, not a server-side file operation.

Checks

uv sync --frozen --all-groups --all-extras
uv run --frozen ruff check .
uv run --frozen ruff format --check .
uv run --frozen pytest
uv run --frozen python -m build --no-isolation
uv venv --clear .wheel-venv
uv pip install --python .wheel-venv/bin/python dist/*.whl
.wheel-venv/bin/python -c "import langextract_mcp.server"

For a real local-host smoke test, set LX_SAMPLING_COMMAND to a command that reads the LangExtract prompt on stdin and emits a real JSON extraction envelope, then run:

uv run --frozen python example/real_sampling_smoke.py

The smoke script is not a product provider and does not claim fixture output is live inference.

License

Apache-2.0. The repository release must include the LICENSE file.