ConceptNet MCP Server

How to use

Install and start the server, then connect your MCP client to perform four core actions: look up concepts, query concepts with filters, discover related concepts, and compute semantic relatedness between two concepts. You will choose between a minimal output format for efficiency or a verbose format when you need full metadata and context. Use the minimal format for most chat interfaces and production apps, and switch to verbose when debugging or performing deep analyses.

How to install

# Install prerequisites and clone the project
# This example uses Python and pip, but you can adapt to your environment as needed
# Ensure Python 3.9+ is available

# Clone the repository
git clone https://github.com/infinitnet/conceptnet-mcp.git
cd conceptnet-mcp

# Install in development mode
pip install -e .

# Optional: install dev dependencies
pip install -e .[dev]

# Start a local stdio server (default)
conceptnet-mcp

# Or start the Python module variant
python -m conceptnet_mcp.server

# To run an HTTP transport locally on port 3001
conceptnet-mcp-http

# Or manually start the HTTP server via Python snippet
python -c "from conceptnet_mcp.server import run_http_server; run_http_server('0.0.0.0', 8080)"

Configuration and runtime notes

You can configure the MCP server with environment variables to tailor the external ConceptNet API usage, server binding, logging, and rate limits. Common options include setting the base API URL, API version, host, port, and log verbosity. For example, you may adjust rate limits to suit your traffic and enable verbose logging during development.

# ConceptNet API settings
CONCEPTNET_API_BASE_URL=https://api.conceptnet.io
CONCEPTNET_API_VERSION=5.7

# Server settings
MCP_SERVER_HOST=localhost
MCP_SERVER_PORT=3000
LOG_LEVEL=INFO

# Rate limiting (example values)
CONCEPTNET_RATE_LIMIT=100
CONCEPTNET_RATE_PERIOD=60

Security and best practices

Run the MCP server behind a trusted network boundary or in an environment with appropriate access controls. Keep API keys and internal endpoints secured, and use rate limiting to prevent abuse. When exposing an HTTP endpoint, consider additional authentication or IP allowlists if you publish the service to the public internet.

Troubleshooting and tips

If the server fails to start, check that the required Python version is installed and that the port you intend to use is free. Review logs for any import or runtime errors, and confirm that environment variables are set correctly before launching the server. If you switch between stdio and HTTP transports, ensure your client is configured to the corresponding transport and that the server process has the appropriate listening address and port.

Notes on output formats

All tools support a verbose flag to control the level of detail. The default is the minimal format, which reduces data size and speeds up responses. Verbose responses include complete metadata, statistics, and the original API responses and are useful for debugging or in-depth analysis.

concept_lookup

Retrieve detailed information about a specific concept, including relationships and properties.

concept_query

Perform advanced queries with multiple criteria to find concepts and relations.

related_concepts

Find concepts semantically related to a given concept using ConceptNet’s embeddings.

concept_relatedness

Calculate a numeric semantic relatedness score between two concepts across languages.