fastmcp 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

fastmcp/cli/claude.py

@@ -3,7 +3,7 @@
 import json
 import sys
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Dict
 
 from ..utilities.logging import get_logger
 
@@ -30,16 +30,17 @@ def update_claude_config(
     *,
     with_editable: Optional[Path] = None,
     with_packages: Optional[list[str]] = None,
-    force: bool = False,
+    env_vars: Optional[Dict[str, str]] = None,
 ) -> bool:
-    """Add the MCP server to Claude's configuration.
+    """Add or update a FastMCP server in Claude's configuration.
 
     Args:
         file_spec: Path to the server file, optionally with :object suffix
         server_name: Name for the server in Claude's config
         with_editable: Optional directory to install in editable mode
         with_packages: Optional list of additional packages to install
-        force: If True, replace existing server with same name
+        env_vars: Optional dictionary of environment variables. These are merged with
+            any existing variables, with new values taking precedence.
     """
     config_dir = get_claude_config_path()
     if not config_dir:
@@ -54,18 +55,17 @@ def update_claude_config(
         if "mcpServers" not in config:
             config["mcpServers"] = {}
 
-        if server_name in config["mcpServers"]:
-            if not force:
-                logger.warning(
-                    f"Server '{server_name}' already exists in Claude config. "
-                    "Use `--force` to replace.",
-                    extra={"config_file": str(config_file)},
-                )
-                return False
-            logger.info(
-                f"Replacing existing server '{server_name}' in Claude config",
-                extra={"config_file": str(config_file)},
-            )
+        # Always preserve existing env vars and merge with new ones
+        if (
+            server_name in config["mcpServers"]
+            and "env" in config["mcpServers"][server_name]
+        ):
+            existing_env = config["mcpServers"][server_name]["env"]
+            if env_vars:
+                # New vars take precedence over existing ones
+                env_vars = {**existing_env, **env_vars}
+            else:
+                env_vars = existing_env
 
         # Build uv run command
         args = ["run", "--with", "fastmcp"]
@@ -89,11 +89,17 @@ def update_claude_config(
         # Add fastmcp run command
         args.extend(["fastmcp", "run", file_spec])
 
-        config["mcpServers"][server_name] = {
+        server_config = {
             "command": "uv",
             "args": args,
         }
 
+        # Add environment variables if specified
+        if env_vars:
+            server_config["env"] = env_vars
+
+        config["mcpServers"][server_name] = server_config
+
         config_file.write_text(json.dumps(config, indent=2))
         logger.info(
             f"Added server '{server_name}' to Claude config",

fastmcp/cli/cli.py

@@ -5,15 +5,16 @@ import importlib.util
 import subprocess
 import sys
 from pathlib import Path
-from typing import Optional, Tuple
+from typing import Optional, Tuple, Dict
 
 import typer
 from typing_extensions import Annotated
+import dotenv
 
 from ..utilities.logging import get_logger
 from . import claude
 
-logger = get_logger(__name__)
+logger = get_logger("cli")
 
 app = typer.Typer(
     name="fastmcp",
@@ -23,6 +24,17 @@ app = typer.Typer(
 )
 
 
+def _parse_env_var(env_var: str) -> Tuple[str, str]:
+    """Parse environment variable string in format KEY=VALUE."""
+    if "=" not in env_var:
+        logger.error(
+            f"Invalid environment variable format: {env_var}. Must be KEY=VALUE"
+        )
+        sys.exit(1)
+    key, value = env_var.split("=", 1)
+    return key.strip(), value.strip()
+
+
 def _build_uv_command(
     file_spec: str,
     with_editable: Optional[Path] = None,
@@ -263,7 +275,7 @@ def run(
 
     except Exception as e:
         logger.error(
-            "Failed to run server",
+            f"Failed to run server: {e}",
             extra={
                 "file": str(file),
                 "error": str(e),
@@ -304,16 +316,32 @@ def install(
             help="Additional packages to install",
         ),
     ] = [],
-    force: Annotated[
-        bool,
+    env_vars: Annotated[
+        list[str],
         typer.Option(
-            "--force",
+            "--env-var",
+            "-e",
+            help="Environment variables in KEY=VALUE format",
+        ),
+    ] = [],
+    env_file: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--env-file",
             "-f",
-            help="Replace existing server if one exists with the same name",
+            help="Load environment variables from a .env file",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            resolve_path=True,
         ),
-    ] = False,
+    ] = None,
 ) -> None:
-    """Install a FastMCP server in the Claude desktop app."""
+    """Install a FastMCP server in the Claude desktop app.
+
+    Environment variables are preserved once added and only updated if new values
+    are explicitly provided.
+    """
     file, server_object = _parse_file_path(file_spec)
 
     logger.debug(
@@ -324,7 +352,6 @@ def install(
             "server_object": server_object,
             "with_editable": str(with_editable) if with_editable else None,
             "with_packages": with_packages,
-            "force": force,
         },
     )
 
@@ -345,14 +372,31 @@ def install(
             )
             name = file.stem
 
+    # Process environment variables if provided
+    env_dict: Optional[Dict[str, str]] = None
+    if env_file or env_vars:
+        env_dict = {}
+        # Load from .env file if specified
+        if env_file:
+            try:
+                env_dict.update(dotenv.dotenv_values(env_file))
+            except Exception as e:
+                logger.error(f"Failed to load .env file: {e}")
+                sys.exit(1)
+
+        # Add command line environment variables
+        for env_var in env_vars:
+            key, value = _parse_env_var(env_var)
+            env_dict[key] = value
+
     if claude.update_claude_config(
         file_spec,
         name,
         with_editable=with_editable,
         with_packages=with_packages,
-        force=force,
+        env_vars=env_dict,
     ):
-        print(f"Successfully installed {name} in Claude app")
+        logger.info(f"Successfully installed {name} in Claude app")
     else:
-        print(f"Failed to install {name} in Claude app")
+        logger.error(f"Failed to install {name} in Claude app")
         sys.exit(1)

fastmcp/server.py

@@ -53,7 +53,11 @@ class Settings(BaseSettings):
     For example, FASTMCP_DEBUG=true will set debug=True.
     """
 
-    model_config: SettingsConfigDict = SettingsConfigDict(env_prefix="FASTMCP_")
+    model_config: SettingsConfigDict = SettingsConfigDict(
+        env_prefix="FASTMCP_",
+        env_file=".env",
+        extra="ignore",
+    )
 
     # Server settings
     debug: bool = False
@@ -400,7 +404,6 @@ class FastMCP:
     async def run_stdio_async(self) -> None:
         """Run the server using stdio transport."""
         async with stdio_server() as (read_stream, write_stream):
-            logger.info(f'Starting "{self.name}"...')
             await self._mcp_server.run(
                 read_stream,
                 write_stream,

fastmcp/utilities/logging.py

@@ -3,15 +3,17 @@
 import logging
 from typing import Literal
 
+from rich.logging import RichHandler
+
 
 def get_logger(name: str) -> logging.Logger:
     """Get a logger nested under FastMCP namespace.
 
     Args:
-        name: The name of the logger, which will be prefixed with 'FastMCP.'
+        name: the name of the logger, which will be prefixed with 'FastMCP.'
 
     Returns:
-        A configured logger instance
+        a configured logger instance
     """
     return logging.getLogger(f"FastMCP.{name}")
 
@@ -22,9 +24,8 @@ def configure_logging(
     """Configure logging for FastMCP.
 
     Args:
-        level: The log level to use
+        level: the log level to use
     """
     logging.basicConfig(
-        level=level,
-        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        level=level, format="%(message)s", handlers=[RichHandler(rich_tracebacks=True)]
     )

{fastmcp-0.3.0.dist-info → fastmcp-0.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastmcp
-Version: 0.3.0
+Version: 0.3.2
 Summary: A more ergonomic interface for MCP servers
 Author: Jeremiah Lowin
 License: Apache-2.0
@@ -9,6 +9,7 @@ Requires-Dist: httpx>=0.26.0
 Requires-Dist: mcp<2.0.0,>=1.0.0
 Requires-Dist: pydantic-settings>=2.6.1
 Requires-Dist: pydantic<3.0.0,>=2.5.3
+Requires-Dist: python-dotenv>=1.0.1
 Requires-Dist: typer>=0.9.0
 Provides-Extra: dev
 Requires-Dist: copychat>=0.5.2; extra == 'dev'
@@ -22,7 +23,7 @@ Requires-Dist: ruff; extra == 'dev'
 Description-Content-Type: text/markdown
 
 <!-- omit in toc -->
-# FastMCP 
+# FastMCP 🚀
 
 <div align="center">
 
@@ -30,17 +31,46 @@ Description-Content-Type: text/markdown
 [![Tests](https://github.com/jlowin/fastmcp/actions/workflows/run-tests.yml/badge.svg)](https://github.com/jlowin/fastmcp/actions/workflows/run-tests.yml)
 [![License](https://img.shields.io/github/license/jlowin/fastmcp.svg)](https://github.com/jlowin/fastmcp/blob/main/LICENSE)
 
+The fast, Pythonic way to build MCP servers
+
 </div>
 
-FastMCP is a high-level, intuitive framework for building [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers with Python. While MCP is a powerful protocol that enables LLMs to interact with local data and tools in a secure, standardized way, the specification can be cumbersome to implement directly. FastMCP lets you build fully compliant MCP servers in the most Pythonic way possible - in many cases, simply decorating a function is all that's required.
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers are a new, standardized way to provide context and tools to your LLMs, and FastMCP makes building MCP servers simple and intuitive. Create tools, expose resources, and define prompts with clean, Pythonic code:
+
+```python
+# demo.py
+
+from fastmcp import FastMCP
+
+
+mcp = FastMCP("Demo 🚀")
+
+
+@mcp.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+```
+
+That's it! Give Claude access to the server by running:
+
+```bash
+fastmcp install demo.py
+```
+
+FastMCP handles all the complex protocol details and server management, so you can focus on building great tools. It's designed to be high-level and Pythonic - in most cases, decorating a function is all you need.
+
+
+### Key features:
+* **Fast**: High-level interface means less code and faster development
+* **Simple**: Build MCP servers with minimal boilerplate
+* **Pythonic**: Feels natural to Python developers
+* **Complete***: FastMCP aims to provide a full implementation of the core MCP specification
 
-🚧 *Note: FastMCP is under active development, as is the low-level MCP Python SDK* 🏗️
+(\*emphasis on *aims*)
+
+🚨 🚧 🏗️ *FastMCP is under active development, as is the MCP specification itself. Core features are working but some advanced capabilities are still in progress.* 
 
-Key features:
-* **Intuitive**: Designed to feel familiar to Python developers, with powerful type hints and editor support
-* **Simple**: Build compliant MCP servers with minimal boilerplate
-* **Fast**: High-performance async implementation
-* **Full-featured**: Complete implementation of the MCP specification
 
 <!-- omit in toc -->
 ## Table of Contents
@@ -57,7 +87,9 @@ Key features:
   - [Context](#context)
 - [Deployment](#deployment)
   - [Development](#development)
+    - [Environment Variables](#environment-variables)
   - [Claude Desktop](#claude-desktop)
+    - [Environment Variables](#environment-variables-1)
 - [Examples](#examples)
   - [Echo Server](#echo-server)
   - [SQLite Explorer](#sqlite-explorer)
@@ -113,19 +145,21 @@ fastmcp install server.py
 fastmcp dev server.py
 ```
 
-![MCP Inspector](docs/images/mcp-inspector.png)
+![MCP Inspector](/docs/assets/demo-inspector.png)
 
 ## What is MCP?
 
 The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but specifically designed for LLM interactions. MCP servers can:
 
-- Expose data through **Resources** (like GET endpoints)
-- Provide functionality through **Tools** (like POST endpoints)
+- Expose data through **Resources** (think of these sort of like GET endpoints; they are used to load information into the LLM's context)
+- Provide functionality through **Tools** (sort of like POST endpoints; they are used to execute code or otherwise produce a side effect)
 - Define interaction patterns through **Prompts** (reusable templates for LLM interactions)
+- And more!
+
+There is a low-level [Python SDK](https://github.com/modelcontextprotocol/python-sdk) available for implementing the protocol directly, but FastMCP aims to make that easier by providing a high-level, Pythonic interface.
 
 ## Core Concepts
 
-*Note: All code examples below assume you've created a FastMCP server instance called `mcp`.*
 
 ### Server
 
@@ -140,6 +174,7 @@ mcp = FastMCP("My App")
 # Configure host/port for HTTP transport (optional)
 mcp = FastMCP("My App", host="localhost", port=8000)
 ```
+*Note: All of the following code examples assume you've created a FastMCP server instance called `mcp`, as shown above.*
 
 ### Resources
 
@@ -297,6 +332,10 @@ fastmcp dev server.py --with pandas --with numpy
 fastmcp dev server.py --with-editable .
 ```
 
+#### Environment Variables
+
+The MCP Inspector runs servers in an isolated environment. Environment variables must be set through the Inspector UI and are not inherited from your system. The Inspector does not currently support setting environment variables via command line (see [Issue #94](https://github.com/modelcontextprotocol/inspector/issues/94)).
+
 ### Claude Desktop
 
 Install your server in Claude Desktop:
@@ -309,9 +348,6 @@ fastmcp install server.py --name "My Server"
 
 # With dependencies
 fastmcp install server.py --with pandas --with numpy
-
-# Replace an existing server
-fastmcp install server.py --force
 ```
 
 The server name in Claude will be:
@@ -319,8 +355,38 @@ The server name in Claude will be:
 2. The `name` from your FastMCP instance
 3. The filename if the server can't be imported
 
+#### Environment Variables
+
+Claude Desktop runs servers in an isolated environment. Environment variables from your system are NOT automatically available to the server - you must explicitly provide them during installation:
+
+```bash
+# Single env var
+fastmcp install server.py -e API_KEY=abc123
+
+# Multiple env vars
+fastmcp install server.py -e API_KEY=abc123 -e OTHER_VAR=value
+
+# Load from .env file
+fastmcp install server.py -f .env
+```
+
+Environment variables persist across reinstalls and are only updated when new values are provided:
+
+```bash
+# First install
+fastmcp install server.py -e FOO=bar -e BAZ=123
+
+# Second install - FOO and BAZ are preserved
+fastmcp install server.py -e NEW=value
+
+# Third install - FOO gets new value, others preserved
+fastmcp install server.py -e FOO=newvalue
+```
+
 ## Examples
 
+Here are a few examples of FastMCP servers. For more, see the `examples/` directory.
+
 ### Echo Server
 A simple server demonstrating resources, tools, and prompts:
 
@@ -382,4 +448,4 @@ Schema:
 {get_schema()}
 
 What insights can you provide about the structure and relationships?"""
-```
+```

{fastmcp-0.3.0.dist-info → fastmcp-0.3.2.dist-info}/RECORD

@@ -1,9 +1,9 @@
 fastmcp/__init__.py,sha256=Y5dHGBwyQPgNP5gzOyNIItefvMZ3vJLdom1oV8A1u_k,248
 fastmcp/exceptions.py,sha256=K0rCgXsUVlws39hz98Tb4BBf_BzIql_zXFZgqbkNTiE,348
-fastmcp/server.py,sha256=gZCl4ppLWYjM4L6MXJxr-jh9ngjHjaFSFTLpofmgtmA,21987
+fastmcp/server.py,sha256=JttRzt1bnJGBU8mL4Bo764WHFXQ09QqKc_CUT3390WM,21997
 fastmcp/cli/__init__.py,sha256=7hrwtCHX9nMd9qcz7R_JFSoqbL71fC35cBLXBS430mg,88
-fastmcp/cli/claude.py,sha256=hId0cTmAfCrav72Hg5LeO0SPPNyEVtIOcoKVAy8gD3k,3390
-fastmcp/cli/cli.py,sha256=Mru5j0_apXBnLBEd6DMICGPUk52DN3eyjSc1B973M2M,10028
+fastmcp/cli/claude.py,sha256=mepURIVhlwQQYgkjgmuJCS841QAs9Mu-xRxdLpfCO0o,3628
+fastmcp/cli/cli.py,sha256=gzpgUseCR5tkdyZumjjxyAIYJLMeAdyJ5zgRHC9EL_M,11407
 fastmcp/prompts/__init__.py,sha256=4BsMxoYolpoxg74xkkkzCFL8vvdkLVJ5cIPNs1ND1Jo,99
 fastmcp/prompts/base.py,sha256=WaSsfyFSsUPUbcApkGy3Pm-Ne-Gk-5ZwU3efqRYn1mQ,4996
 fastmcp/prompts/manager.py,sha256=EkexOB_N4QNtC-UlZmIcWcau91ceO2O1K4_kD75pA_A,1485
@@ -17,10 +17,10 @@ fastmcp/tools/__init__.py,sha256=ZboxhyMJDl87Svjov8YwNYwNZi55P9VhmpTjBZLesnk,96
 fastmcp/tools/base.py,sha256=JPdTx8SAl5pKsHyIVxnsLG88f3fbjnopDTOAZ_PoVQE,2585
 fastmcp/tools/tool_manager.py,sha256=PT6XHcQWzhdC6kfdsJaddRn7VLps4nAs5FMG8l1j8Zc,1617
 fastmcp/utilities/__init__.py,sha256=-imJ8S-rXmbXMWeDamldP-dHDqAPg_wwmPVz-LNX14E,31
-fastmcp/utilities/logging.py,sha256=t2w5bwtrkxHxioWSy5vY8esxLQxyxN8tfFZ1FI3Cb6E,704
+fastmcp/utilities/logging.py,sha256=VLJdNc0tIYoQZmpobehLUnWrQz7NXnuwSqrDlFt2RF0,738
 fastmcp/utilities/types.py,sha256=jFlZMZsKrJg4NWc1vTBIILLoHpTVwSd-vxO7ycoRuig,1718
-fastmcp-0.3.0.dist-info/METADATA,sha256=Nu76qWE1nxUHiHF4pczCTMUl8C2hKpXfIeo2Sp1UHxo,11452
-fastmcp-0.3.0.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-fastmcp-0.3.0.dist-info/entry_points.txt,sha256=ff8bMtKX1JvXyurMibAacMSKbJEPmac9ffAKU9mLnM8,44
-fastmcp-0.3.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-fastmcp-0.3.0.dist-info/RECORD,,
+fastmcp-0.3.2.dist-info/METADATA,sha256=R64QFKVKLfIVWjOFi-vmEL3At_Dx8rwHTBdjBOTLC30,13617
+fastmcp-0.3.2.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+fastmcp-0.3.2.dist-info/entry_points.txt,sha256=ff8bMtKX1JvXyurMibAacMSKbJEPmac9ffAKU9mLnM8,44
+fastmcp-0.3.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+fastmcp-0.3.2.dist-info/RECORD,,