CasualMarket

CasualMarket is a Taiwan stock market MCP server built on the FastMCP framework. It exposes a suite of tools for real-time pricing, financial analysis, market information, and simulated trading, designed to be consumed by any MCP-enabled client via the standard MCP/SSE interface. The server is published on PyPI and can be started through the uvx (Python) ecosystem. Once running, you can list available tools and invoke them through the MCP SSE endpoint, enabling you to query stock prices, retrieve financial statements, monitor market indicators, and run simulated trades with realistic costs and timing controls. The configuration examples show how to wire the server into Claude Desktop, Cursor, VS Code Claude integration, or other MCP clients by pointing them at the CasualMarket MCP entry and enabling optional logging and caching controls. The server also supports caching, rate limiting, and monitoring to balance performance and resource use.

Prerequisites

• Python 3.12 or newer
• Internet access for package installation
• An MCP client or environment that supports the MCP protocol (Claude Desktop, Cursor, VS Code Claude extension, etc.)

Installation steps

1. Install the uv package manager (required to run MCP servers with uvx). You can install uv via your preferred method, for example:

   • Using pipx (recommended): pipx install uv
   • Or using pip (if available in your environment): pip install uv

2. Install and run the CasualMarket MCP server via uvx using the repository URL provided in the README. The following command demonstrates the standard run pattern (adjust paths as needed):

   uvx --from git+https://github.com/sacahan/CasualMarket casual-market-mcp

   This will fetch the CasualMarket MCP module from GitHub and start it under the MCP framework. Alternatively, you can point uvx to a local clone of the repository and run the same command using the local path instead of the git URL.

3. If you plan to connect through Claude Desktop, Cursor, or VS Code Claude integration, add the following configuration (example shown for Claude Desktop):

   { "mcpServers": { "casual-market": { "command": "uvx", "args": ["--from", "git+https://github.com/sacahan/CasualMarket", "casual-market-mcp"], "env": { "LOG_LEVEL": "INFO" } } } }

4. Verify operation by hitting the MCP server or using an MCP client to list tools and call specific functions (see the example in the README for how to list tools and query a stock price).

Notes

• If you prefer a local development setup, you can clone the CasualMarket repository and point uvx to the local path in the --from argument.
• Consider adjusting caching, rate limiting, and logging via environment variables described in the README to tune performance.

Tips and common considerations:

• Environment variables to tune behavior include LOG_LEVEL, MARKET_MCP_API_TIMEOUT, MARKET_MCP_CACHE_TTL, MARKET_MCP_CACHE_MAX_SIZE, MARKET_MCP_RATE_LIMITING_ENABLED, and related rate limit settings. Adjust these to balance responsiveness with external API usage.
• When deploying via Docker, the project provides a dedicated path (scripts/docker-run.sh) to pull, build, and run containers. The Docker setup exposes an SSE endpoint for MCP clients at http://localhost:8000/sse and standard docs at /docs.
• If you see slow responses or API timeouts, consider increasing MARKET_MCP_API_TIMEOUT and adjusting MARKET_MCP_CACHE_TTL and MEMORY usage limits to ensure cached results remain useful.
• Always ensure the MCP server is reachable by your clients (check network/firewall settings) and that the MCP endpoint (SSE) is accessible from the client’s network.
• The tool catalog includes over 23 professional tools across real-time stock pricing, financial analysis, market information, and simulated trading; use the provided example to explore tools like get_taiwan_stock_price and other analytics endpoints.