Provides containerized deployment of the MCP server with volume mounting for persistent storage of API keys, simplifying setup and operation across different environments.
Offers integration with Python applications through the fastmcp client library, enabling programmatic access to MCP tools and capabilities from Python code.
MCP Dockerized Server
This repository provides a minimal MCP server based on [fastmcp]. The server exposes the Streamable HTTP transport and protects all requests using a simple API key authentication system.
Use Cases
- Local AI Model Serving: Run an MCP server locally to interact with AI models through a standardized interface
- Development Environment: Set up a consistent development environment for applications that consume MCP services
- Prototyping: Quickly test MCP-based applications without complex cloud setup
- Self-hosted AI Solutions: Deploy in environments where cloud-based solutions aren't feasible
- Integration Testing: Use as a stable test backend for applications that depend on MCP services
Installation and Setup
Prerequisites
- Docker and Docker Compose installed on your system
- Basic familiarity with command-line operations
- At least 500MB of free disk space
Build and run with Docker
The container stores API keys in /data/api_keys.db
. Mount a volume to
persist keys across restarts.
Run with Docker Compose
Create the included docker-compose.yml
file and start the service:
This builds the image if necessary and launches the server on port 8000.
The API key database is persisted in the mcp_data
volume.
Generate API keys
Use the management CLI inside the container to create keys:
If you're using Docker Compose:
Generated keys are written to /data/api_keys.db
inside the container or the mounted volume.
You can confirm the file exists by listing it with a one-off container:
The printed key can then be supplied via the X-API-Key
header or
api_key
query parameter when calling the server.
Endpoints
The server exposes two simple HTTP endpoints:
Path | Method | Description |
---|---|---|
/mcp | POST | Streamable HTTP transport for MCP requests. Requires a valid API key. |
/generate-key | POST | Generates a new API key. Requires an existing valid API key. |
Interactive API documentation is available at /docs
(also accessible via /doc
) with the raw schema at /openapi.json
.
Example requests
Generate a key via HTTP
Call the MCP endpoint
You can issue JSON-RPC requests directly. The example below sends a ping
request:
Call a tool via HTTP
Tools are invoked using the tools/call
method. Provide the tool name and any
arguments in the JSON-RPC payload. The example below runs the built-in
terminal
tool:
Using the Python Client
For more advanced interaction you can use the fastmcp
Python client:
Plugins
Additional tools and resources can be added by placing modules in the
plugins
package. Each module should expose a setup(server)
function
which receives the FastMCP
instance and registers tools or resources.
All modules in this package are automatically imported on startup.
This repository ships with a terminal
plugin providing a simple tool
for running commands on the host system.
Creating a Custom Plugin
- Create a new Python module in the
plugins
directory - Implement the
setup(server)
function - Register your tools or resources
Example plugin structure:
Configuration
The server can be configured using the following environment variables:
Variable | Description | Default |
---|---|---|
MCP_DB_PATH | Path to the SQLite database file for API keys | /data/api_keys.db |
MCP_PORT | Port on which the server listens | 8000 |
Example usage with custom values:
Troubleshooting
API Key Issues
Problem: "Invalid API key" errors when making requests
Solution: Ensure you're using a valid API key generated with the generate-key
command. Keys are stored in the database file at the path specified by MCP_DB_PATH
.
Problem: API keys not persisting across container restarts Solution: Make sure you're mounting a volume correctly to store the database file:
Connection Issues
Problem: Cannot connect to the server Solution: Verify that:
- The server is running (
docker ps
should show the container) - You're connecting to the correct port (default is 8000)
- There are no firewall rules blocking the connection
Problem: Connection refused errors Solution: Check if the port is already in use by another service:
Plugin Issues
Problem: Custom plugins aren't being loaded Solution: Ensure your plugin:
- Is placed in the
plugins
directory - Contains a
setup(server)
function - Has no syntax errors
Problem: Errors when calling tools Solution: Check the server logs for detailed error messages:
Performance Tuning
For production use, consider adjusting these settings:
- Increase container resources (CPU/memory) for heavy workloads
- Use a dedicated volume with high I/O performance for the database
- Set appropriate timeout values for your specific use case
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A minimal, containerized MCP server that exposes a Streamable HTTP transport with API key authentication, allowing secure access to MCP endpoints.
Related MCP Servers
- -securityAlicense-qualityAn MCP server that exposes HTTP methods defined in an OpenAPI specification as tools, enabling interaction with APIs via the Model Context Protocol.Last updated -2PythonMIT License
mcp-confluentofficial
AsecurityAlicenseAqualityAn MCP server implementation built to interact with Confluent Kafka and Confluent Cloud REST APIs.Last updated -245277TypeScriptMIT License- -securityAlicense-qualityA reference implementation for creating an MCP server supporting Streamable HTTP & SSE Transports with OAuth authorization, allowing developers to build OAuth-authorized MCP servers with minimal configuration.Last updated -5TypeScriptMIT License
- -securityAlicense-qualityA server that implements the Model Context Protocol (MCP) with StreamableHTTP transport, enabling standardized interaction with model services through a RESTful API interface.Last updated -1951JavaScriptMIT License