model-mcp

model-mcp is a Model Context Protocol (MCP) server that discovers local model runtimes and exposes their endpoint metadata to MCP clients such as Copilot.

It checks common localhost endpoints for:

• Ollama (http://127.0.0.1:11434/api/tags)
• LM Studio (http://127.0.0.1:1234/v1/models)
• LocalAI or OpenAI-compatible local servers (http://127.0.0.1:8080/v1/models)

The server does not proxy prompts or model completions. It advertises where local models are available so an MCP-aware client can inspect and use that configuration.

Install

Run from a source checkout

git clone https://github.com/shakerg/model-mcp.git
cd model-mcp
npm install
npm run build

In the GitHub Copilot app, add a local/stdio MCP server. Use the absolute path to the checkout:

{
  "servers": {
    "local-models": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/model-mcp/dist/index.js"]
    }
  }
}

You can also run the checkout directly with npm start; it communicates over stdio and normally waits silently for an MCP client.

Install from npm

If npm view model-mcp version returns the release you want, add a local/stdio MCP server in the GitHub Copilot app and let npx download and launch it:

{
  "servers": {
    "local-models": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "model-mcp@<published-version>"]
    }
  }
}

Use the package's exact published version for reproducible installation.

Install from Docker

Images are stored in this repository's GitHub Container Registry package. After the matching version is available, add a local/stdio server that keeps stdin open and maps the cross-platform Docker host name:

{
  "servers": {
    "local-models": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--add-host",
        "host.docker.internal:host-gateway",
        "ghcr.io/shakerg/model-mcp:<published-version>"
      ]
    }
  }
}

The image defaults to the common model ports on host.docker.internal, allowing the container to discover Ollama, LM Studio, and LocalAI running on the host. Use MODEL_MCP_ENDPOINTS to override those endpoints.

Install from an MCP registry

After a release is listed in an MCP registry, supported Copilot clients can choose either the npm or Docker package instead of entering the command manually. The installer reads server.json and presents these optional environment fields:

• MODEL_MCP_ENDPOINTS
• MODEL_MCP_TIMEOUT_MS
• MODEL_MCP_ALLOW_REMOTE

Leave a field unset to use its default. Registry installation is available only after the package or image version referenced by server.json has been published.

[!WARNING] https://github.com/shakerg/model-mcp is a repository page, not a remote MCP endpoint. Do not enter it as an HTTP, SSE, or streamable HTTP server URL. This project is a local stdio server; treating the GitHub URL as an MCP endpoint sends protocol requests to a web page and results in HTTP errors such as 422 with an HTML response.

Configuration

Set MODEL_MCP_ENDPOINTS to a comma-separated list of local endpoint base URLs when your model servers use different ports.

MODEL_MCP_ENDPOINTS="http://127.0.0.1:11434,http://127.0.0.1:1234" npm start

By default, only loopback hosts and Docker's host.docker.internal gateway are accepted. Set MODEL_MCP_ALLOW_REMOTE=true only when you intentionally want to expose other model endpoints through the MCP server.

Optional environment variables:

| Variable | Default | Description | | --- | --- | --- | | MODEL_MCP_ENDPOINTS | Common Ollama, LM Studio, and LocalAI localhost URLs | Comma-separated endpoint base URLs. | | MODEL_MCP_TIMEOUT_MS | 2000 | Timeout for each endpoint discovery request. | | MODEL_MCP_ALLOW_REMOTE | false | Allows non-loopback endpoints when set to true. |

MCP capabilities

Tools

• list_local_models - returns configured endpoints, reachability, and discovered model IDs.
• describe_model_endpoint - inspects one endpoint by ID, such as ollama or lm-studio.
• get_model_endpoint_config - returns an MCP configuration snippet that can be used by Copilot or another MCP client.

Resources

• local-models://endpoints - JSON description of discovered endpoints and models.
• local-models://copilot-config - JSON MCP configuration example for launching this server.

Development

npm run test:package
npm run test:docker

test:package type-checks the source, validates server.json against its official MCP schema, creates the npm tarball, checks that dist/index.js is executable and included, installs the tarball into a clean temporary project, and completes an MCP initialize/list-tools exchange over stdio.

test:docker builds the production image and completes the same MCP initialize/list-tools exchange through docker run.

When Docker-related source changes merge to main, the Publish container GitHub Actions workflow builds linux/amd64 and linux/arm64 images and pushes both the package version and latest tags to this repository's GHCR package. The workflow rejects an existing version tag, so image changes require a version bump.

Publishing checklist

Publication requires maintainer access to npm, GitHub Container Registry, and the MCP registry:

1. Run npm run test:package.
2. Confirm the version matches in package.json, server.json, and src/index.ts, and that package.json#mcpName matches server.json#name.
3. Publish with the project owner's npm account or configured trusted publishing.
4. Confirm npm view model-mcp version returns the released version.
5. Merge the release PR to main to publish the multi-platform image, then make the GHCR package public if it does not inherit public visibility and verify its version tag.
6. Only then publish server.json to an MCP registry.