Personal MCP Fastmcp
์์ด๋ณด์ฉ MCP ์บ๋ฆญํฐ ๋ณด์ผ๋ฌํ๋ ์ดํธ โ FastMCP(Python) ๊ณจ๊ฒฉ
Ask AI about Personal MCP Fastmcp
Powered by Claude ยท Grounded in docs
I know everything about Personal MCP Fastmcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
personal-mcp-fastmcp
์์ด๋ณด์ฉ MCP ์บ๋ฆญํฐ โ FastMCP(Python) ๊ณจ๊ฒฉ ~50์ค์ง๋ฆฌ server.py ํ๋. Windows ยท macOS ยท Linux ๋ชจ๋ ๋์ผํ๊ฒ ๋์.
0. ์ฌ์ ์ค๋น (ํ ๋ฒ๋ง)
โ Python ํธ๋์ Windows ๋ค์ดํฐ๋ธ์์๋ ์ ๋์ํฉ๋๋ค (Rails์ ๋ฌ๋ฆฌ). WSL2 ์์ด PowerShell๋ง์ผ๋ก OK.
Python 3.11+ ์ค์น ํ์ธ
python3 --version # ๋๋ python --version (Windows)
# 3.11 ์ด์์ด์ด์ผ ํจ. ์์ผ๋ฉด https://python.org ์์ ์ค์น
uv ์ค์น (Python ํจํค์ง ๋งค๋์ , ๊ฐ์ฅ ๋น ๋ฆ)
macOS:
brew install uv
# ๋๋: curl -LsSf https://astral.sh/uv/install.sh | sh
Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# ์ PowerShell ์ฐฝ ์ด์ด์ ํ์ธ
ํ์ธ:
uv --version
uv python install 3.12 # Python ์๋ ์ค์น/๊ด๋ฆฌ๋ uv๊ฐ ํด์ค (์ต์
)
โ ๏ธ macOS์์ Claude Desktop์ด
uv๋ฅผ ๋ชป ์ฐพ๋ ๊ฒฝ์ฐ(ENOENT ์๋ฌ) โsudo ln -s ~/.local/bin/uv /usr/local/bin/uvํ ๋ฒ ์คํ. macOS GUI ์ฑ์ด PATH๋ฅผ ๋ค๋ฅด๊ฒ ์ฝ๊ธฐ ๋๋ฌธ.
๐ช Windows์์
uv๊ฐ PATH์ ์์ผ๋ฉด ์ PowerShell์ ์ด์ด๋ณด์ธ์. ์ฌ์ ํ ์์ผ๋ฉดwhere uv๋ก ์์น ํ์ธ ํ PATH์ ์ถ๊ฐ.
1. 5๋ถ ์์
์์กด์ฑ ์ค์น
cd personal-mcp-fastmcp
uv sync
Claude Desktop์ ์๋ ๋ฑ๋ก (๊ถ์ฅ โ Win/Mac ๋ ๋ค ์๋)
uv run fastmcp install claude-desktop server.py --server-name my-character
์ด ๋ช ๋ น ํ๋๋ก:
- Claude Desktop config ํ์ผ ์์น๋ฅผ OS๋ณ๋ก ์๋ ํ์ง
mcpServersํญ๋ชฉ ์๋ ์ถ๊ฐ- ์์กด์ฑ ๊ฒฝ๋ก ์๋ ์ค์
Claude Desktop ์ฌ์์ โ ์ฑํ ์ฐฝ ์ ๋ ฅ๋ ์ข์ธก ํ๋จ์ ๐จ ์์ด์ฝ์ด ๋ณด์ด๋ฉด ์ฑ๊ณต.
๋์ ํ์ธ
Claude์ ์ ๋ ฅ:
hello ๋๊ตฌ ํธ์ถํด์ค
์ ์ ์๋ต: "์๋ ! ์ด๊ฒ ๋์ ์ฒซ MCP ์บ๋ฆญํฐ์ผ."
2. ์๋ ์ค์ (์๋์ด ์คํจํ ๋)
Claude Desktop ์ค์ ํ์ผ ์์น:
| OS | ๊ฒฝ๋ก |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
mcpServers ํค์ ์ถ๊ฐ:
macOS / Linux:
{
"mcpServers": {
"my-character": {
"command": "uv",
"args": [
"--directory", "/Users/YOUR_NAME/personal-mcp-character/personal-mcp-fastmcp",
"run", "python", "server.py"
]
}
}
}
Windows:
{
"mcpServers": {
"my-character": {
"command": "uv",
"args": [
"--directory", "C:\\Users\\YOUR_NAME\\personal-mcp-character\\personal-mcp-fastmcp",
"run", "python", "server.py"
]
}
}
}
3. ํ์ผ ๊ตฌ์กฐ
personal-mcp-fastmcp/
โโโ server.py # MCP ์๋ฒ ๋ณธ์ฒด (~50์ค)
โโโ gates/
โ โโโ __init__.py
โ โโโ permission.py # read/write/danger ๋ถ๊ธฐ
โโโ pyproject.toml # ์์กด์ฑ 1๊ฐ (mcp[cli])
โโโ claude_desktop_config.example.json # ์๋ ๋ฑ๋ก์ฉ ํ
ํ๋ฆฟ
โโโ README.md
4. ์์ฃผ ์ฐ๋ ๋ช ๋ น์ด ๋ชจ์
| ์์ | ๋ช ๋ น์ด (๋ชจ๋ OS ๋์ผ) |
|---|---|
| ์์กด์ฑ ์ค์น | uv sync |
| Claude Desktop ์๋ ๋ฑ๋ก | uv run fastmcp install claude-desktop server.py --server-name my-character |
| MCP ์ธ์คํํฐ (UI๋ก ํ ์คํธ) | uv run fastmcp dev server.py |
| ์๋ฒ๋ง ์ง์ ์คํ (๋๋ฒ๊ทธ) | uv run python server.py |
| ๋๊ตฌ ๋ชฉ๋ก ํ์ธ (๋ค๋ฅธ ํฐ๋ฏธ๋) | echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | uv run python server.py |
| ์์กด์ฑ ์ถ๊ฐ | uv add ํจํค์ง๋ช
|
| ๊ฐ์ํ๊ฒฝ ํ์ฑํ (ํ์์) | macOS/Linux: source .venv/bin/activate ยท Windows: .venv\Scripts\activate |
5. ๋ณธ์ธ ๋๊ตฌ ์ถ๊ฐํ๋ ๋ฒ
server.py์ ๋ฐ์ฝ๋ ์ดํฐ ํ ์ค + ํจ์ ํ๋:
@mcp.tool()
def my_tool(arg1: str) -> str:
"""์ด ๋๊ตฌ๊ฐ ๋ฌด์์ ํ๋์ง โ Claude๊ฐ ์ด๊ฑธ ๋ณด๊ณ ํ๋จํฉ๋๋ค."""
gate.check("read", action=f"my_tool: {arg1}") # ์ํ๋ ๋ถ๋ฅ
return "๊ฒฐ๊ณผ"
์ํ๋ ์ธ ๊ฐ์ง:
"read"โ ์กฐํ๋ง, ์๋ ํต๊ณผ"write"โ ์ฐ๊ธฐ/์ถ๊ฐ, 5๋ถ ์๋์ฐ ์๋ ์น์ธ"danger"โ ์ญ์ /๋ฉ์ผ/๊ฒฐ์ฌ, ๋งค๋ฒ ์ฌ์ฉ์ ํ์ธ
6. ์ต์ โ ๊ฐ์ ํ๊ฒฝ์ ๋ง๊ฒ ์ถ๊ฐ
๊ธฐ๋ณธ ๊ณจ๊ฒฉ์๋ ์๋์ ์ผ๋ก ๋น ์ ธ์์ต๋๋ค. ๋ณธ์ธ ํ๊ฒฝ์ ๋ง์ถฐ ์ฑ์ฐ์ธ์.
์ํฌ๋ฆฟ ๊ด๋ฆฌ (OS๋ณ)
macOS โ Keychain:
security add-generic-password -s "notion-api" -a "$(whoami)" -w "secret_xxx"
import subprocess
def get_secret(name):
return subprocess.run(
["security", "find-generic-password", "-s", name, "-w"],
capture_output=True, text=True, check=True,
).stdout.strip()
Windows โ Credential Manager:
# pip install keyring
import keyring
keyring.set_password("notion-api", "default", "secret_xxx") # ํ ๋ฒ๋ง
NOTION_KEY = keyring.get_password("notion-api", "default")
Linux โ Secret Service (libsecret):
# pip install keyring secretstorage
# ์ keyring ์ฝ๋ ๊ทธ๋๋ก ๋์ (๋ฐฑ์๋๋ libsecret์ด ์๋ ์ ํ๋จ)
์ต์๋์ธ vault ์ด๋ํฐ
from pathlib import Path
import os
VAULT = Path(os.environ.get("OBSIDIAN_VAULT", str(Path.home() / "obsidian-vault")))
@mcp.tool()
def search_vault(query: str) -> str:
"""์ต์๋์ธ vault์์ ๋งํฌ๋ค์ด ๋ฉ๋ชจ ๊ฒ์."""
gate.check("read", action=f"vault search: {query}")
matches = []
for md in VAULT.rglob("*.md"):
text = md.read_text(errors="ignore")
if query.lower() in text.lower():
matches.append(f"## {md.relative_to(VAULT)}\n{text[:500]}")
return "\n\n---\n\n".join(matches[:5]) or "๊ฒฐ๊ณผ ์์"
Pathlib์ ์ฐ๋ฉด Win/Mac/Linux ๊ฒฝ๋ก๊ฐ ์๋ ํธํ๋ฉ๋๋ค.
HITL ์ฑ๋ ๊ต์ฒด (gates/permission.py์ _ask_user)
- macOS ์๋ฆผ:
osascript -e 'display dialog "..." buttons {"๊ฑฐ๋ถ","์น์ธ"}' - Windows ์๋ฆผ: PowerShell
[System.Windows.Forms.MessageBox]::Show(...) - ํฌ๋ก์คํ๋ซํผ: Telegram bot / Pushover / Slack webhook
7. ํธ๋ฌ๋ธ์ํ
| ์ฆ์ | ์์ธ / ํด๊ฒฐ |
|---|---|
| Claude Desktop์ ๐จ ์์ด์ฝ ์ ๋ณด์ | 1. config ํ์ผ์ ์ ํํ ์ถ๊ฐ๋๋์ง ํ์ธ 2. ์ค์ โ ๊ฐ๋ฐ์ โ ๋ก๊ทธ ํ์ธ 3. Claude Desktop ์์ ์ข ๋ฃ ํ ์ฌ์์ |
spawn uv ENOENT (macOS) | sudo ln -s ~/.local/bin/uv /usr/local/bin/uv (GUI ์ฑ PATH ์ด์) |
spawn uv ENOENT (Windows) | where uv๋ก ๊ฒฝ๋ก ํ์ธ ํ config์ command์ ์ ๋๊ฒฝ๋ก ์
๋ ฅ (์: "C:\\Users\\me\\.local\\bin\\uv.exe") |
| ํ๊ธ ์ถ๋ ฅ ๊นจ์ง | PYTHONIOENCODING=utf-8 ํ๊ฒฝ๋ณ์ ์ค์ |
mcp ํจํค์ง import ์๋ฌ | uv sync ๋ค์ ์คํ, Python ๋ฒ์ 3.11+ ํ์ธ |
์๋งค ํ๋ก์ ํธ
- ๊ฐ์ ์ปจ์
Rails 8 ๋ฒ์ :
../personal-mcp-rails/ - ๋ธ๋ก๊ทธ: MCP๋ ๋ด ์ ์ฉ ์บ๋ฆญํฐ๋ค
