mcp-servers 0.1.3

Simple MCP Server Collection, Packaged

mcp_servers

A collection of MCP servers and a CLI tool to manage them.

Disclaimer

This project is created for personal use and does not guarantee stable behavior. It is made public solely as a reference for other programmers. The project is highly unstable, premature, and may produce undesired outcomes, so use it at your own risk.

Development Setup

git clone [e-mail]:assagman/mcp_servers.git

cd mcp_servers

uv venv --python 3.12 && source .venv/bin/activate

uv sync --extra dev

Examples

All LLM models are used from openrouter.ai, so on OPENROUTER_API_KEY env var is mandatory for this project to interact with a LLM model.

cp ./examples/.env.example ./examples/.env then set your OPENROUTER_API_KEY in ./examples/.env. In these examples google/gemini-2.5-flash-preview is picked as the LLM model since it's the best fit model for this workflow I experienced. You need to buy credits on https://openrouter.ai/settings/credits to experiment. Even some free alternatives can work sometimes, but either they do not produce consistent outputs or there are some problems with the hosting server like rate limits or unavailability. Make sure you select models with tools usage. Generally Google and OpenAI models, even with smaller/cheaper ones, works well.

Example usage: as a package in client code

python examples/run_filesystem_agent.py

without making any changes, this command should be executed successfully as is, and it'll operate on a temporary directory.

Example usage: as a separate, dedicated MCP server

mcpserver start --server filesystem --port 8765 --allowed-dir $(pwd) --detach

Above command should start MCP server for filesystem in the background process. ps aux | rg mcpserver is expected to show this related process.

python examples/run_filesystem_agent_2.py

after some chat with agent, please run below to stop the MCP server:

mcpserver stop --server filesystem

This specific example uses CLI app utility to start/stop MCP seperately from the client code (different from the first example).

Others

brave_search

Create .env file in the top-level project directory, set BRAVE_API_KEY in it. Then excecute:

mcpserver start --server brave_search --port 8766 --detach

This will start the MCP Server. Let's test it with example agent:

python examples/run_brave_search_agent.py

This will allow user to chat with agent, using MCP server for Brave Search. After some chat, you can stop it via:

mcpserver stop --server brave_search

searxng_search

This is very similar to brave_search, but since public searxng instances may not meet users requirements in terms of configurations/settings like rate limiting, formats etc., it's better to run a local searxng instance and make this MCP server use it.

To do that, podman or docker can be used to run a official searxng container. This will require a minimal searxng settings setup. To manage all these minimal steps more easily, mcpserver CLI tool provide commands to start/stop searxng container:

mcpserver run_external_container --container searxng

This will require user to have SEARXNG_BASE_URL set as environment variable. You can simply set this variable in ~/.mcp_servers/.env file and tool will automatically pick it up, without any sourcing process performed.

Confirm that the container is up-and-running (podman ps or docker ps). Then, start searxng_search MCP server:

mcpserver start --server searxng_search --port 8767

Now, this MCP server can be accessible by agents. Here is an example usage:

python examples/run_searxng_search_agent.py

after some experimentation, you can shutdown both MCP Server for searxng and the external container via:

mcpserver stop --server searxng_search for MCP server

mcpserver stop_external_container --container searxng for external searxng container

Testing specs

• macOS - arm64
• python 3.12