QuantGeekDev/mcp-framework

MCP-Framework is a framework for building Model Context Protocol (MCP) servers elegantly in TypeScript.
MCP-Framework gives you architecture out of the box, with automatic directory-based discovery for tools, resources, and prompts. Use our powerful MCP abstractions to define tools, resources, or prompts in an elegant way. Our cli makes getting started with your own MCP server a breeze
Features
- 🛠️ Automatic discovery and loading of tools, resources, and prompts
- Multiple transport support (stdio, SSE, HTTP Stream)
- TypeScript-first development with full type safety
- Built on the official MCP SDK
- Easy-to-use base classes for tools, prompts, and resources
- Out of the box authentication for SSE endpoints (OAuth 2.1, JWT, API Key)
Projects Built with MCP Framework
The following projects and services are built using MCP Framework:
- ### tip.md
A crypto tipping service that enables AI assistants to help users send cryptocurrency tips to content creators directly from their chat interface. The MCP service allows for:
- Checking wallet types for users
- Preparing cryptocurrency tips for users/agents to complete
Setup instructions for various clients (Cursor, Sage, Claude Desktop) are available in their MCP Server documentation.
Support our work
Read the full docs here
Creating a repository with mcp-framework
Using the CLI (Recommended)
CLI Usage
The framework provides a powerful CLI for managing your MCP server projects:
Project Creation
Options:
--http: Use HTTP transport instead of default stdio
--port : Specify HTTP port (default: 8080)
--cors: Enable CORS with wildcard (*) access
Adding a Tool
Building and Validation
The framework provides comprehensive validation to ensure your tools are properly documented and functional:
Validating Tools
This command checks that all tools using Zod schemas have descriptions for every field. The validation runs automatically during build, but you can also run it standalone:
- ✅ **During build**: npm run build automatically validates tools
- ✅ **Standalone**: mcp validate for manual validation
- ✅ **Development**: Use defineSchema() helper for immediate feedback
- ✅ **Runtime**: Server validates tools on startup
**Example validation error:**
**Integrating validation into CI/CD:**
Adding a Prompt
Adding a Resource
Development Workflow
1. **Create your project:**
2. **Add tools:**
3. **Define your tool schemas with automatic validation:**
4. **Build with automatic validation:**
5. **Optional: Run standalone validation:**
6. **Test your server:**
7. **Add to MCP Client** (see Claude Desktop example below)
**Pro Tips:**
- Use defineSchema() during development for immediate feedback
- Build process automatically catches missing descriptions
- Server startup validates all tools before accepting connections
- Use TypeScript's autocomplete with MCPInput for better DX
Using with Claude Desktop
Local Development
Add this configuration to your Claude Desktop config file:
**MacOS**: ~/Library/Application Support/Claude/claude_desktop_config.json
**Windows**: %APPDATA%/Claude/claude_desktop_config.json
After Publishing
Add this configuration to your Claude Desktop config file:
**MacOS**: ~/Library/Application Support/Claude/claude_desktop_config.json
**Windows**: %APPDATA%/Claude/claude_desktop_config.json
Building and Testing
1. Make changes to your tools
2. Run npm run build to compile
3. The server will automatically load your tools on startup
Environment Variables
The framework supports the following environment variables for configuration:
| Variable | Description | Default |
|-----------------------|-------------------------------------------------------|-------------|
| MCP_ENABLE_FILE_LOGGING | Enable logging to files (true/false) | false |
| MCP_LOG_DIRECTORY | Directory where log files will be stored | logs |