CatMapper MCP
OfficialClick on "Deploy 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., "@CatMapper MCP search categories for felines and show the top result"
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.
CatMapper MCP
A local Model Context Protocol (MCP) server that lets an MCP-compatible AI application use selected CatMapper API operations. It communicates with the API over HTTP; it does not connect directly to the database.
Available tools
The server supports category search, node and page inspection, dataset and metadata lookup, synchronous translation, upload status, and merge preview. Merge preview does not perform a merge. Upload status reports on an existing task; the server does not start uploads.
General editing, uploads, and merge execution are not yet exposed. Those operations need verification of their complete API-side validation and atomic-write guarantees before they can be added. This server does not expose a generic arbitrary-URL or API-call tool.
Some lookup and translation endpoints are public; authenticated endpoints use the permissions of the account associated with the supplied API key. The CatMapper API currently logs the returned rows of synchronous translations, so consider that before translating sensitive data.
Related MCP server: Amiqus MCP server
Installation
You need Python 3.10 or newer, a CatMapper API key, and an application that supports local MCP servers using stdio. Install from a checkout:
git clone https://github.com/ProjectCatMapper/CatMapperMCP.git
cd CatMapperMCP
python3 -m venv .venv
.venv/bin/python -m pip install .On Windows, use .venv\Scripts\python.exe instead of .venv/bin/python. Configure your MCP application to run the installed catmapper-mcp executable with CATMAPPER_API_KEY in its environment. For example, the following illustrates the common mcpServers configuration format; consult your application's documentation for its configuration location and supported secret references:
{
"mcpServers": {
"catmapper": {
"command": "/absolute/path/to/CatMapperMCP/.venv/bin/catmapper-mcp",
"env": {
"CATMAPPER_API_KEY": "YOUR_API_KEY"
}
}
}
}Replace the path and configure the key using your application's secret storage or protected environment-variable facility when available. Do not paste your key into a chat, commit it to a repository, or share a configuration file containing it. On Windows, the executable is typically .venv\Scripts\catmapper-mcp.exe. Restart or enable the server as required by your application; it should discover the tools automatically.
CATMAPPER_API_URL is optional and defaults to https://api.catmapper.org. Use an HTTPS origin for another CatMapper deployment; plain HTTP is allowed only for localhost development. The server does not follow HTTP redirects. Generating a replacement CatMapper API key invalidates the previous key; update the MCP configuration accordingly.
Development and tests
.venv/bin/python -m pip install -e '.[test]'
.venv/bin/python -m pytest -qTests use mocked or local HTTP responses and do not write to a CatMapper database. Standard output is reserved for MCP protocol communication.
Versioning
Package versions are derived automatically from Git by hatch-vcs when the package is built or installed; no local Git hook or manual version-file edit is required. A release tag such as v1.2.3 gives that release its version. Builds after a tag receive a development version containing the commit distance and Git identifier; builds with tracked uncommitted changes include a dirty marker. Untagged history also produces development versions. Create release tags deliberately when ready to release; commits and pushes do not create or publish releases automatically.
Run .venv/bin/catmapper-mcp --version to see the version recorded when the package was installed. Reinstall after changing commits to refresh it. Build from a Git checkout with history and tags available, or from a packaged source distribution; a GitHub-generated source archive without Git metadata is not a supported build source.
License
MIT.
Available Tools
11 toolsget_datasetCRead-only
Get a dataset's details and category data; optionally filter by domain.
Inputs: cmid (required), database (required), domain, children.
get_nodeBRead-only
Get a node's properties and USES relationships by CMID.
Inputs: cmid (required), database (required).
get_node_pageCRead-only
Get the explore-page representation of a CatMapper node.
Inputs: cmid (required), database (required).
list_datasetsCRead-only
List datasets in a CatMapper database.
Inputs: database (required).
list_domainsCRead-only
List public domains in a CatMapper database.
Inputs: database (required).
list_propertiesCRead-only
List metadata properties in a CatMapper database.
Inputs: database (required).
list_subdomainsBRead-only
List public subdomains in a CatMapper database.
Inputs: database (required).
preview_mergeARead-only
Preview a category merge and identify cyclic parent references. Does not apply the merge.
Inputs: database (required), keep_cmid (required), delete_cmid (required).
search_categoriesCRead-only
Search categories and entities. Database is ArchaMap or SocioMap; contexts and dataset are CMIDs.
Inputs: database (required), term, limit, domain, +7 more.
translateCRead-only
Translate tabular category data synchronously. The CatMapper API may log returned rows.
Inputs: key (required), table (required), domain (required), database (required), +9 more.
upload_statusBRead-only
Check a queued upload's status and progress using its task ID.
Inputs: task_id (required), cursor.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools target clearly distinct resources or actions, such as listing datasets versus searching categories. The main potential confusion is between get_node and get_node_page, which both retrieve node representations but at different levels of detail.
Names consistently use snake_case and mostly follow a predictable verb_noun pattern: list_*, get_*, search_*, and preview_*. Minor deviations are translate as a verb-only name and upload_status as a noun phrase, but the overall convention is readable and stable.
With 11 tools, the surface is well-scoped for a database exploration and data-processing server. Each tool appears to cover a distinct operation rather than bloating the set with redundant variants.
Core read, search, listing, and translation workflows are covered, but there are notable lifecycle gaps. preview_merge does not apply merges, upload_status exists without an upload-initiating tool, and there are no create/update/delete operations for the main data entities.
Maintenance
Related MCP Connectors
Authenticated MCP access to the AIKI open knowledge commons.
Read-only MCP for AI usage profiles, leaderboards, stats, and docs; no writes or private data.
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
Related MCP Servers
AlicenseAqualityDmaintenanceEnables calling 120+ AI models and reading live web pages (scrape, crawl, structured extract) from any MCP client using one API key.9143 npmMIT- AlicenseAqualityCmaintenanceEnables Claude, ChatGPT and other MCP clients to read an Amiqus ID account—clients, onboarding records and steps, check results, templates, case status counts and webhooks—and, when writes are enabled, create records.9MIT
- AlicenseNot gradedqualityBmaintenanceExposes scattered business REST APIs and read-only databases to AI clients through a single MCP endpoint with unified API-key authentication, service- and operation-level authorization, department-scoped filtering, masking, and audit logging. AI agents discover only the tools and data they are permitted to use, without needing to know endpoint addresses, SQL, or credentials.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to list, search, inspect, and recommend publicly available, ready-to-use AI products and interactive experiences through a read-only remote MCP endpoint.MIT