mcpforge
A Python library to build MCP servers with decorators, auto-generating JSON Schema from type hints and including built-in filesystem and HTTP servers.
What is mcpforge?
mcpforge is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to python library to build mcp servers with decorators, auto-generating json schema from type hints and including built-in filesystem and http servers.
A Python library to build MCP servers with decorators, auto-generating JSON Schema from type hints and including built-in filesystem and HTTP servers.
This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- A Python library to build MCP servers with decorators, auto-
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx mcpforgeConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use mcpforge
mcpforge is a Python library that makes building MCP servers as simple as decorating class methods, automatically generating JSON Schema from Python type hints and docstrings so you can turn any Python function into a callable MCP tool without writing boilerplate protocol code. It ships with two built-in ready-to-use server implementations — FilesystemTools for sandboxed file operations and HttpTools for fetching URLs — and supports both tools and resources as first-class concepts. Python developers use it to prototype and ship custom MCP integrations quickly, connecting their existing Python code to Claude, OpenAI, and other MCP-compatible AI clients.
Prerequisites
- Python 3.9 or later
- pip for installing the mcpforge package
- An MCP-compatible client such as Claude Desktop or Cursor
- Basic familiarity with Python type hints and class-based design
- No external API keys required for the framework itself
Install mcpforge
Install the mcpforge package from PyPI using pip.
pip install mcpforgeCreate your first MCP server
Define a class with the @serve decorator and annotate methods with @tool. Type hints and docstrings become the JSON Schema that clients see. Save this as, for example, hello.py.
from mcpforge import serve, tool
@serve(name="hello", version="0.1.0")
class HelloTools:
@tool
def greet(self, name: str = "world") -> str:
"""Say hello to someone."""
return f"Hello, {name}!"Run the server
Use the mcpforge CLI to start your server. The argument format is module:ClassName.
python -m mcpforge run hello:HelloToolsUse a built-in server (optional)
mcpforge ships with FilesystemTools (sandboxed list_dir, read_file, search) and HttpTools (fetch_url with size limits). Run them directly without writing any code.
# Filesystem server:
python -m mcpforge run mcpforge.builtins:FilesystemTools
# HTTP server:
python -m mcpforge run mcpforge.builtins:HttpToolsConfigure Claude Desktop
Add the server to claude_desktop_config.json. Point command at python and args at the mcpforge run command for your module. Update cwd to the directory containing your Python module.
{
"mcpServers": {
"my-tools": {
"command": "python",
"args": ["-m", "mcpforge", "run", "hello:HelloTools"],
"cwd": "/path/to/your/project"
}
}
}mcpforge Examples
Client configuration (Claude Desktop)
Example claude_desktop_config.json entry running a custom mcpforge server. Update the module name and cwd to match your project.
{
"mcpServers": {
"my-tools": {
"command": "python",
"args": ["-m", "mcpforge", "run", "hello:HelloTools"],
"cwd": "/Users/yourname/my-mcp-project"
}
}
}Prompts to try
Sample prompts once an mcpforge-based server is connected to Claude Desktop.
- "Say hello to Alice using the greet tool."
- "List the files in /Users/me/documents using the filesystem server."
- "Read the file /Users/me/notes.txt."
- "Fetch the content of https://example.com using the HTTP tool."
- "What tools does the my-tools MCP server expose?"Troubleshooting mcpforge
ModuleNotFoundError when running the server
Ensure mcpforge is installed in the same Python environment that is invoked by the command in your MCP config. Use an absolute path to the Python binary (e.g. /Users/yourname/.venv/bin/python) to avoid virtual environment confusion.
Type hints are not generating correct JSON Schema for tool arguments
mcpforge uses Python's inspect module to read type annotations. Ensure you are using standard types (str, int, float, bool, list, dict) or Pydantic models. Avoid Union types without explicit Optional annotation, and make sure all method parameters have type hints.
Tools are not appearing in Claude Desktop after adding the config
Verify the cwd path exists and contains your Python module. Test the server startup command manually in a terminal: 'python -m mcpforge run hello:HelloTools'. Fix any Python errors before restarting Claude Desktop.
Frequently Asked Questions about mcpforge
What is mcpforge?
mcpforge is a Model Context Protocol (MCP) server that python library to build mcp servers with decorators, auto-generating json schema from type hints and including built-in filesystem and http servers. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install mcpforge?
Follow the installation instructions on the mcpforge GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with mcpforge?
mcpforge works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is mcpforge free to use?
Yes, mcpforge is open source and available under the MIT License license. You can use it freely in both personal and commercial projects.
mcpforge Alternatives — Similar Developer Tools Servers
Looking for alternatives to mcpforge? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.
Ecc
★ 188.2kThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Javaguide
★ 155.8kJava 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发
Gemini CLI
★ 104.5kA secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in
Awesome MCP Servers
★ 87.3k⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.
MCP Servers
★ 86.0kModel Context Protocol Servers
CC Switch
★ 77.5kA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
Browse More Developer Tools MCP Servers
Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up mcpforge in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use mcpforge?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.