Skip to main content
Glama
CatMapper MCP

CatMapper MCP

Official

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 -q

Tests 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 tools
get_datasetC
Read-only

Get a dataset's details and category data; optionally filter by domain.

Inputs: cmid (required), database (required), domain, children.

get_nodeB
Read-only

Get a node's properties and USES relationships by CMID.

Inputs: cmid (required), database (required).

get_node_pageC
Read-only

Get the explore-page representation of a CatMapper node.

Inputs: cmid (required), database (required).

list_datasetsC
Read-only

List datasets in a CatMapper database.

Inputs: database (required).

list_domainsC
Read-only

List public domains in a CatMapper database.

Inputs: database (required).

list_propertiesC
Read-only

List metadata properties in a CatMapper database.

Inputs: database (required).

list_subdomainsB
Read-only

List public subdomains in a CatMapper database.

Inputs: database (required).

preview_mergeA
Read-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_categoriesC
Read-only

Search categories and entities. Database is ArchaMap or SocioMap; contexts and dataset are CMIDs.

Inputs: database (required), term, limit, domain, +7 more.

translateC
Read-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_statusB
Read-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

    B3.1/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables calling 120+ AI models and reading live web pages (scrape, crawl, structured extract) from any MCP client using one API key.
      9
      143 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      9
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes 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