fuzzy-match-mcp
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@fuzzy-match-mcpFind best matches for 'Samsung Galaxy S24' from my product list"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Fuzzy Match MCP
A Python-based Model Context Protocol (MCP) server for deterministic fuzzy text matching.
It can normalize text, compare strings, rank possible matches, group duplicate values, and explain why two values match or differ. The server uses RapidFuzz for similarity scoring and can be used from MCP clients such as Cursor.
Features
Normalize text before comparison
Compare two strings using multiple similarity algorithms
Rank the best matches from a list
Detect and group probable duplicates
Explain matching results using token overlap
Use specialized matching profiles for companies, products, and addresses
Select different scoring strategies
Run locally through MCP over
stdioTestable with
pytest
Related MCP server: EntityIdentification
Available MCP tools
normalize_text
Normalizes a text value before fuzzy matching.
Example input:
{
"value": " Müller & Söhne GmbH! ",
"profile": "general"
}Example result:
{
"original": " Müller & Söhne GmbH! ",
"profile": "general",
"normalized": "muller and sohne gmbh"
}compare_strings
Compares two strings and returns detailed similarity scores.
Example input:
{
"first": "Deutsche Bank AG",
"second": "Deutsche Bank Aktiengesellschaft",
"threshold": 90,
"profile": "company",
"strategy": "strict"
}The response includes:
Normalized values
Individual similarity scores
Selected strategy
Final selected score
Match decision
find_best_matches
Ranks candidate strings according to their similarity with a query.
Example input:
{
"query": "Samsung Galaxy S24",
"choices": [
"Apple iPhone 15",
"Samsung Galaxy S24 128GB",
"Galaxy S24 Smartphone",
"Google Pixel 9"
],
"limit": 3,
"threshold": 40,
"profile": "product",
"strategy": "weighted"
}find_duplicate_groups
Groups values that probably represent the same entity.
Example input:
{
"values": [
"Deutsche Bank AG",
"Deutsche-Bank Aktiengesellschaft",
"Deutsche Bank",
"Commerzbank AG",
"Commerz Bank",
"Amazon Germany GmbH"
],
"threshold": 80,
"profile": "company",
"strategy": "strict"
}This is useful for:
Customer-data cleanup
Product-catalog deduplication
Company-name matching
Imported CSV cleanup
Contact-list deduplication
explain_match
Compares two values and explains the result using normalized tokens and score information.
Example input:
{
"first": "Samsung Galaxy S24 128GB Black",
"second": "Galaxy S24 Black 128 GB",
"threshold": 75,
"profile": "product",
"strategy": "strict"
}The response includes:
Common tokens
Tokens found only in the first value
Tokens found only in the second value
Token-overlap percentage
A deterministic explanation
Final match decision
Matching profiles
The server supports the following normalization profiles.
Profile | Description |
| Lowercases text, removes accents and punctuation, and collapses whitespace |
| Applies general normalization and removes common legal company suffixes |
| Standardizes product units and joins model names such as |
| Standardizes common address terms such as |
Company-profile example
Deutsche Bank AG
Deutsche Bank AktiengesellschaftBoth normalize approximately to:
deutsche bankProduct-profile example
Samsung Galaxy S 24 128 GBNormalizes to:
samsung galaxy s24 128gbMatching strategies
Strategy | Description |
| Standard character similarity |
| Finds the best matching substring |
| Sorts tokens before comparison |
| Compares unique token sets |
| Uses RapidFuzz's weighted ratio |
| Uses a composite score designed to reduce permissive partial matches |
The strict strategy excludes partial_ratio from the final composite score because partial matching can be misleading when a short string appears inside a much longer string.
Thresholds
Similarity scores range from 0 to 100.
90–100: very strict80–89: useful default for names and product titles70–79: more permissiveBelow
70: may create more false-positive matches
A result is considered a match when:
selected_score >= thresholdThe ideal threshold depends on the dataset and the acceptable false-positive rate.
Project structure
fuzzy-match-mcp/
├── .cursor/
│ └── mcp.json
├── fuzzy_match_mcp/
│ ├── __init__.py
│ ├── grouping.py
│ ├── matching.py
│ ├── server.py
│ ├── tools.py
│ └── validators.py
├── tests/
│ ├── __init__.py
│ └── test_matching.py
├── main.py
├── pyproject.toml
├── README.md
└── uv.lockRequirements
Python 3.10 or newer
uvMCP Python SDK
RapidFuzz
pytest for development
Installation
Clone the repository:
git clone <your-repository-url>
cd fuzzy-match-mcpInstall the dependencies:
uv syncIf you are creating the project from scratch:
uv add "mcp[cli]" rapidfuzz
uv add --dev pytestRunning the tests
uv run pytestRunning with MCP Inspector
Use MCP Inspector during development:
uv run mcp dev main.pyThis opens an MCP development interface where the registered tools can be inspected and called.
Running as a local stdio server
uv run python main.pyThe process waits for MCP JSON-RPC messages through standard input.
Do not type into the terminal while the server is running over stdio. A blank terminal input is not a valid MCP JSON-RPC message.
Do not use ordinary print() statements in the server because standard output is reserved for MCP communication. Use logging through standard error instead.
Cursor configuration
Create:
.cursor/mcp.jsonUse the following configuration on Windows:
{
"mcpServers": {
"fuzzy-match": {
"type": "stdio",
"command": "${workspaceFolder}/.venv/Scripts/python.exe",
"args": [
"${workspaceFolder}/main.py"
]
}
}
}Then:
Open the repository root in Cursor.
Open Customize → MCPs.
Enable
fuzzy-match.Click Reload after changing the registered tools.
Use Cursor Agent to call the MCP tools.
Cursor starts the Python process automatically. Do not manually run main.py at the same time.
Example Cursor Agent prompts
Normalize text
Use the fuzzy-match normalize_text tool to normalize:
" Müller & Söhne GmbH! "
Use the general profile.Compare company names
Use the fuzzy-match compare_strings tool.
Compare:
- Deutsche Bank AG
- Deutsche Bank Aktiengesellschaft
Use:
- profile: company
- strategy: strict
- threshold: 90Rank product matches
Use the fuzzy-match find_best_matches tool.
Query:
Samsung Galaxy S24
Choices:
- Apple iPhone 15
- Samsung Galaxy S24 128GB
- Galaxy S24 Smartphone
- Google Pixel 9
Use the product profile and return the best three matches.Group duplicates
Use the fuzzy-match find_duplicate_groups tool with:
- Deutsche Bank AG
- Deutsche-Bank Aktiengesellschaft
- Deutsche Bank
- Commerzbank AG
- Commerz Bank
- Amazon Germany GmbH
Use:
- profile: company
- strategy: strict
- threshold: 80Explain a match
Use the fuzzy-match explain_match tool to compare:
- Samsung Galaxy S24 128GB Black
- Galaxy S24 Black 128 GB
Use:
- profile: product
- strategy: strict
- threshold: 75How it works
The request flow is:
MCP client
↓
MCP tool in tools.py
↓
Input validation in validators.py
↓
Matching or grouping logic
↓
RapidFuzz
↓
Structured JSON resultNormalization happens before similarity scoring. It can include:
Unicode case folding
Accent removal
Punctuation replacement
Whitespace cleanup
Profile-specific transformations
Performance notes
find_best_matches compares one query against each candidate.
find_duplicate_groups performs pairwise comparisons. Its approximate comparison count is:
n × (n - 1) / 2For this reason, duplicate grouping is intentionally limited to 500 values in the current version.
The grouping implementation uses union-find. If A matches B and B matches C, all three values can be placed in the same group even when A and C do not directly exceed the threshold.
Current limitations
Duplicate grouping is pairwise and is not intended for very large datasets.
Company suffixes and address aliases are rule-based and may not cover every country.
Product normalization supports only a small set of common units.
Fuzzy matching does not prove that two real-world entities are identical.
Thresholds should be evaluated against domain-specific examples before automatic merging.
Planned improvements
Structured record matching
Batch matching
Threshold evaluation
Custom normalization options
Additional international company suffixes
CSV import and export
Better canonical-value selection
More matching profiles
MCP resources and reusable prompts
Contributing
Contributions are welcome.
Suggested workflow:
git checkout -b feature/my-change
uv sync
uv run pytestBefore submitting a change:
Add tests for new behavior
Keep MCP tools focused
Avoid writing to standard output
Preserve structured JSON responses
Document new profiles and strategies
License
Add your chosen license before publishing the project.
A common choice for an open-source MCP server is the MIT License.
Available Tools
5 toolscompare_stringsC
Compare two strings using fuzzy matching.
Strategies:
- ratio
- partial
- token_sort
- token_set
- weighted
- strict
Args:
first: First text value.
second: Second text value.
threshold: Minimum score required for a match.
profile: Normalization profile.
strategy: Score-selection strategy.
| Name | Required | Description | Default |
|---|---|---|---|
| first | Yes | ||
| second | Yes | ||
| profile | No | general | |
| strategy | No | weighted | |
| threshold | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It describes fuzzy matching and strategies but omits details like case sensitivity, how threshold is applied, normalization effects, or output shape. The output schema exists but is not referenced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and uses bullet points for strategies and args, which is clear. However, it redundantly lists arg names that are already in the schema, wasting space that could be used for additional guidance. A more concise and informative approach would be preferred.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no annotations, and an output schema, the description should cover return values and typical usage. It does not mention the output format (a score? a boolean?) or provide examples, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It lists parameter names but provides no semantic details: e.g., what each 'profile' does, valid threshold range, strategy definitions. This barely adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Compare two strings using fuzzy matching' and lists specific strategies, making the tool's purpose explicit. It distinguishes itself from siblings like 'normalize_text' and 'find_best_matches' by focusing on pairwise comparison with multiple algorithms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives (e.g., 'find_best_matches' or 'explain_match'). While strategies are listed, there is no explanation of which strategy suits what scenario, leaving the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
explain_matchB
Compare two strings and explain why they match or differ.
Args:
first: First text value.
second: Second text value.
threshold: Minimum score required for a match.
profile: Normalization profile.
strategy: Score-selection strategy.
| Name | Required | Description | Default |
|---|---|---|---|
| first | Yes | ||
| second | Yes | ||
| profile | No | general | |
| strategy | No | strict | |
| threshold | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states basic functionality without disclosing side effects, computational cost, or that the tool is read-only. The description adds little beyond what is expected from the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the main purpose stated first. The parameter list is slightly redundant given the schema, but it does not add unnecessary length. Overall, it is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters (2 required, 2 enums) and no annotations, the description covers the basic operation but omits details about return value format (though output schema exists) and when to use specific profiles or strategies. It is minimally adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. However, it merely restates parameter names and types (e.g., 'First text value') without adding meaningful behavioral constraints or semantics, such as explaining the effect of different profiles or strategies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: compare two strings and explain why they match or differ. It distinguishes itself from siblings like compare_strings (which just compares) and find_best_matches (which finds best match rather than explaining a specific pair).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an explanation of string matching is needed, but lacks explicit guidance on when to use this tool versus alternatives like compare_strings or find_duplicate_groups. No exclusions or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
find_best_matchesC
Find and rank candidate strings most similar to a query.
Args:
query: Text to search for.
choices: Candidate values.
limit: Maximum number of matches.
threshold: Minimum similarity score.
profile: Normalization profile.
strategy: Score-selection strategy.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| choices | Yes | ||
| profile | No | general | |
| strategy | No | weighted | |
| threshold | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only lists parameters without explaining side effects, permissions, or output behavior beyond ranking. Critical traits like read-only or mutation status are absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and structured as a docstring with a clear one-line summary. It lists parameters efficiently without extraneous text, though the parameter descriptions are too terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, enums) and the presence of an output schema, the description omits crucial context such as how ranking works, how threshold and strategy interact, and when to use specific profiles. Sibling tools are not referenced for complementary use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds minimal meaning beyond parameter names (e.g., 'profile: Normalization profile' is vague). It does not explain enum options (e.g., what 'product' profile does) or the effect of strategy choices, failing to compensate for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Find and rank candidate strings most similar to a query,' which is a specific verb+resource. It differentiates the tool from siblings like compare_strings (comparison) and normalize_text (normalization) by focusing on similarity ranking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like compare_strings or explain_match. There is no mention of prerequisites or exclusions, leaving the agent without context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
find_duplicate_groupsB
Group strings that probably represent the same entity.
Useful for:
- company-name deduplication
- customer-name cleanup
- product catalogue cleanup
- contact-list cleanup
Args:
values: Values to examine.
threshold: Minimum score for joining a group.
profile: Normalization profile.
strategy: Score-selection strategy.
| Name | Required | Description | Default |
|---|---|---|---|
| values | Yes | ||
| profile | No | general | |
| strategy | No | strict | |
| threshold | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes the grouping action but lacks details on edge cases (e.g., empty list, duplicate values), performance considerations, or how scoring works internally. The brief parameter explanations do not cover behavioral nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with a clear lead sentence, bullet-point use cases, and a labeled parameter list. It avoids unnecessary words and front-loads the core purpose, making it scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, 2 enums, output schema present), the description covers purpose and basic parameter semantics. However, it omits expected output format (though output schema exists), behavioral constraints, and more detailed usage context relative to siblings, leaving room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides short explanations for each parameter (e.g., threshold: 'Minimum score for joining a group'), adding meaning beyond the schema's names and types. However, explanations are minimal and do not elaborate on how values affect behavior, leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Group strings that probably represent the same entity,' which is a specific verb and resource. It lists concrete use cases like company-name deduplication and customer-name cleanup, distinguishing it from sibling tools like compare_strings or find_best_matches that focus on comparison or single match retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Useful for' scenarios, giving context on when to use the tool. However, it does not discuss when not to use it or contrast with alternatives like compare_strings for pairwise comparison or explain_match for explanation, limiting guidance for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
normalize_textA
Normalize text before fuzzy matching.
Profiles:
- general: standard text normalization
- company: removes legal company suffixes
- product: standardizes product units and model names
- address: standardizes common address terms
Args:
value: Text to normalize.
profile: Type of normalization to apply.
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | ||
| profile | No | general |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It briefly describes the effect of each profile (e.g., 'removes legal company suffixes') but does not disclose side effects, performance characteristics, or limitations. Minimal behavioral context but adequate for a simple normalization function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: two sentences plus bullet points for profiles and an Args section. No unnecessary information. Front-loaded with the purpose, making it quick to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage context, parameters, and profiles. Since an output schema exists (not shown but noted), it does not need to explain return values. Lacks examples but is complete enough given the tool's simplicity and sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clearly defines both parameters: 'value' as text to normalize and 'profile' with enumerated options and their purposes. This adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it normalizes text before fuzzy matching, and lists four specific profiles (general, company, product, address) that distinguish its functionality. The name and description together make the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'before fuzzy matching', providing clear context for when to use this tool. While it does not explicitly exclude alternatives, the sibling tools (compare_strings, find_best_matches, etc.) are clearly about matching/comparing, so usage intent is well communicated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.1.0- First observed
compare_strings - First observed
explain_match - First observed
find_best_matches - First observed
find_duplicate_groups - First observed
normalize_text
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: direct comparison, normalization, candidate ranking, duplicate grouping, and detailed explanation. No overlap in functionality.
All tool names follow a consistent verb_noun pattern (compare_strings, normalize_text, etc.) with clear and predictable naming.
5 tools is well-scoped for a fuzzy matching server, covering essential operations without being excessive or sparse.
The surface covers normalization, comparison, matching, deduplication, and explanation. A minor gap is the lack of a tool to list available profiles/strategies, but descriptions provide that information.
Maintenance
Related MCP Connectors
Primarily to be used as a template repository for developing MCP servers with FastMCP in Python, P…
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
Related MCP Servers
- FlicenseNot gradedqualityFmaintenanceA production-ready MCP server built with FastAPI, providing an enhanced tool registry for creating, managing, and documenting AI tools for Large Language Models (LLMs).34-
- AlicenseNot gradedqualityDmaintenanceA MCP server that helps determine if two sets of data belong to the same entity by comparing both exact and semantic equality through text normalization and language model integration.1MIT
- AlicenseBqualityDmaintenanceA complete MCP server for Retrieval-Augmented Generation with file management and vector memory for agents. Supports multiple document formats (PDF, DOCX, TXT, MD, CSV, JSON) with semantic search using Hugging Face embeddings and ChromaDB for efficient vector storage.1191MIT
- AlicenseNot gradedqualityDmaintenanceA comprehensive Python MCP server with built-in knowledge base (SQLite + FTS5), web management interface, and flexible tool grouping system. Supports multiple transport protocols (stdio, SSE, HTTP Stream) with zero external dependencies.MIT