Claude İçin Yerel MCP Sunucusu Nasıl Oluşturulur: Dosyalar, Komutlar, Ekran Görüntüleri ve Uygulama Kontrolü

Claude, yalnızca bir sohbet arayüzü olmaktan çıktığında çok daha kullanışlı hale gelir.

Yerel bir MCP sunucusu, Claude'un gerçek bilgisayarınızla etkileşime girmesini sağlar: yerel dosyalar, onaylanmış komutlar, ekran görüntüleri ve uygulama başlatmaları. Önemli olan kısım ham erişim değil, kontrollü erişimdir.

Bu rehberde, Claude için pratik, dar kapsamlı ve gerçek iş akışlarında kullanılabilecek kadar güvenli bir yerel MCP sunucusu kuracağız.

Bir şey inşa etmeye başlamadan önce kısa bir not

Bu makale, "bilgisayar kontrolü"nün sorumsuz versiyonundan bilinçli olarak kaçınır.

Claude'a sınırsız kabuk erişimi, tam dosya sistemi yetkisi veya güvenlik önlemleri olmadan bilgisayarınızda değişiklik yapma izni vermeyeceğiz. Kötü bir yerel MCP sunucusu oluşturmanın en hızlı yolu, devasa bir run_anything() aracını ortaya çıkarmak ve buna yenilik demektir.

Daha iyi olan model şudur:

• izin verilen dizinler
• izin verilen komutlar
• güvenli varsayılanlar
• insan tarafından okunabilir günlükler
• açık yanıtlar
• salt okunur ve eylem araçları arasında net ayrım

Claude her şeyi yapabiliyorsa, bir demo inşa etmişsinizdir.

Claude doğru şeyleri güvenli bir şekilde yapabiliyorsa, kullanılabilir bir şey inşa etmişsinizdir.

Bu mimariyi öğrenmek neden değerli?

Yerel bir MCP sunucusunun değeri yenilik değil, sürtünmeyi azaltmasıdır.

Yerel bir araç katmanı olmadan iş akışınız şöyle görünür:

1. Claude'a ne yapacağını sorun
2. Cevabı kopyalayın
3. Klasörü kendiniz açın
4. Komutu kendiniz çalıştırın
5. Ekran görüntüsünü kendiniz alın
6. Sonucu tekrar sohbete yapıştırın

Yerel bir MCP sunucusuyla bu döngü önemli ölçüde kısalır. Claude, ihtiyaç duyduğu bağlamı inceleyebilir, dar kapsamlı araçları kullanabilir ve gerçek bilgisayarınızın durumuna dayalı bir cevap döndürebilir.

Bu, aşağıdakiler için kullanışlıdır:

• geliştirme iş akışları
• günlük incelemesi
• içerik operasyonları
• araştırma hatları
• masaüstü otomasyonu
• tekrarlanan yönetici görevleri

Ve araç katmanı size ait olduğu için, modelin nerede duracağını tam olarak siz seçersiniz.

Yapay Zekayı öğrenmek ve kariyerinizde önde olmak mı istiyorsunuz?

Şunları paylaşıyorum:

1.000'den fazla Yapay Zeka komutu

Yapay Zeka araçları ve otomasyonları

Kariyer ve LinkedIn büyüme ipuçları

Özenle seçilmiş teknoloji ve üretkenlik kaynakları

Buradan abone olun:

https://bytebuilders.beehiiv.com/subscribe

Daha fazla Yapay Zeka ipucu için beni takip edin

👇

İnşa ettiğimiz tasarım

Beş araçtan oluşan yerel bir sunucu kuracağız:

1. list_files — onaylı klasörlerin içinde ne olduğunu görün
2. read_file — güvenli metin tabanlı dosyaları açın
3. run_command — onaylı yerel komutlardan oluşan küçük bir seti çalıştırın
4. take_screenshot — ekran görüntüsünü bilinen bir konuma kaydedin
5. open_target — bir uygulama, dosya, klasör veya URL açın

Bu kapsam kasıtlıdır.

Claude'u yerel bir makinede anlamlı bir şekilde kullanışlı kılmaya yeter, ancak güvensiz genel amaçlı otomasyona dönüşmez.

Zihinsel model şöyle görünmelidir:

Claude → MCP istemcisi → yerel MCP sunucusu → dar araçlar → işletim sistemi

Claude asla doğrudan işletim sisteminizle konuşmamalıdır. MCP sunucunuz aradaki kontrol düzlemidir.

Teknoloji yığını

Yerel bir yapı için Python temiz bir seçimdir çünkü resmi MCP SDK'sı olgundur, FastMCP soyutlaması kısadır ve Python, dosya sistemi, alt süreç ve masaüstü betikleme işleri için en kolay dil olmaya devam etmektedir 4 2.

Şunları kullanacağız:

• Python 3.11+
• MCP sunucu çalışma zamanı için mcp[cli]
• Platformlar arası ekran görüntüleri için mss
• Dosya erişimi, alt süreç çağrıları ve işletim sistemi yönetimi için standart kütüphane modülleri

Yeni bir proje oluşturun:

1mkdir local-mcp-server
2cd local-mcp-server
3uv init --python 3.11
4uv add "mcp[cli]>=1.0,<2.0" "mss>=9.0,<10.0"

Dekoratör tabanlı FastMCP stili, protokol katmanını yolunuzdan uzak tutar, böylece bağlantı kablolaması yerine araç kalitesine odaklanabilirsiniz 4 5.

Basit bir proje düzeni iyi çalışır:

1mkdir local-mcp-server
2cd local-mcp-server
3uv init --python 3.11
4uv add "mcp[cli]>=1.0,<2.0" "mss>=9.0,<10.0"

v1 için karmaşık bir mimariye ihtiyacınız yok. İhtiyacınız olan şey netliktir.

Gerçek sunucu

server.py dosyasını oluşturun ve politika odaklı bir uygulama ile başlayın.

1from __future__ import annotations
2
3import json
4import os
5import platform
6import shlex
7import subprocess
8from pathlib import Path
9from typing import Any
10
11import mss
12from mcp.server.fastmcp import FastMCP
13
14app = FastMCP("local-computer-control", json_response=True)
15
16HOME = Path.home()
17PROJECT_ROOT = Path(__file__).parent.resolve()
18CAPTURE_DIR = PROJECT_ROOT / "captures"
19CAPTURE_DIR.mkdir(exist_ok=True)
20
21ALLOWED_ROOTS = [
22    HOME / "Documents",
23    HOME / "Desktop",
24    PROJECT_ROOT,
25]
26
27ALLOWED_COMMANDS = {
28    "pwd",
29    "ls",
30    "git status",
31    "git diff --stat",
32    "python --version",
33    "node --version",
34    "npm --version",
35}
36
37READABLE_EXTENSIONS = {
38    ".txt",
39    ".md",
40    ".json",
41    ".py",
42    ".js",
43    ".ts",
44    ".tsx",
45    ".jsx",
46    ".yaml",
47    ".yml",
48    ".toml",
49    ".csv",
50    ".log",
51}
52
53def _resolve_path(raw_path: str) -> Path:
54    path = Path(raw_path).expanduser().resolve()
55    for root in ALLOWED_ROOTS:
56        root = root.resolve()
57        if path == root or root in path.parents:
58            return path
59    raise ValueError(f"Yola izin verilmiyor: {path}")
60
61def _ensure_safe_command(command: str) -> str:
62    normalized = " ".join(shlex.split(command))
63    if normalized not in ALLOWED_COMMANDS:
64        raise ValueError(
65            "Komuta izin verilmiyor. Gerçekten ihtiyacınız varsa, ALLOWED_COMMANDS listesine açıkça ekleyin."
66        )
67    return normalized
68
69@app.tool()
70def list_files(path: str = "~") -> dict[str, Any]:
71    """Onaylı bir dizindeki dosya ve klasörleri listeler."""
72    target = _resolve_path(path)
73    if not target.is_dir():
74        raise ValueError(f"Bir dizin değil: {target}")
75
76    items = []
77    for child in sorted(target.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower())):
78        items.append(
79            {
80                "name": child.name,
81                "path": str(child),
82                "type": "directory" if child.is_dir() else "file",
83            }
84        )
85
86    return {
87        "path": str(target),
88        "count": len(items),
89        "items": items,
90    }
91
92@app.tool()
93def read_file(path: str, max_chars: int = 12000) -> dict[str, Any]:
94    """Onaylı bir konumdan güvenli bir metin dosyasını okur."""
95    target = _resolve_path(path)
96    if not target.is_file():
97        raise ValueError(f"Bir dosya değil: {target}")
98    if target.suffix.lower() not in READABLE_EXTENSIONS:
99        raise ValueError(f"Desteklenmeyen dosya türü: {target.suffix}")
100
101    content = target.read_text(encoding="utf-8", errors="replace")
102    truncated = len(content) > max_chars
103    content = content[:max_chars]
104
105    return {
106        "path": str(target),
107        "truncated": truncated,
108        "content": content,
109    }
110
111@app.tool()
112def run_command(command: str, cwd: str | None = None, timeout: int = 15) -> dict[str, Any]:
113    """İzin verilen bir yerel komutu çalıştırır."""
114    safe_command = _ensure_safe_command(command)
115    working_dir = _resolve_path(cwd) if cwd else PROJECT_ROOT
116
117    completed = subprocess.run(
118        safe_command,
119        shell=True,
120        cwd=str(working_dir),
121        capture_output=True,
122        text=True,
123        timeout=timeout,
124    )
125
126    return {
127        "command": safe_command,
128        "cwd": str(working_dir),
129        "returncode": completed.returncode,
130        "stdout": completed.stdout.strip(),
131        "stderr": completed.stderr.strip(),
132    }
133
134@app.tool()
135def take_screenshot(name: str = "latest") -> dict[str, Any]:
136    """Bir ekran görüntüsü alır ve yerel olarak kaydeder."""
137    output_path = CAPTURE_DIR / f"{name}.png"
138
139    with mss.mss() as sct:
140        sct.shot(output=str(output_path))
141
142    return {
143        "saved": True,
144        "path": str(output_path),
145    }
146
147@app.tool()
148def open_target(target: str) -> dict[str, Any]:
149    """Yerel işletim sistemini kullanarak onaylı bir dosyayı, klasörü, uygulamayı veya URL'yi açar."""
150    system = platform.system().lower()
151
152    if target.startswith("http://") or target.startswith("https://"):
153        resolved = target
154    else:
155        resolved = str(_resolve_path(target))
156
157    if system == "darwin":
158        subprocess.run(["open", resolved], check=True)
159    elif system == "windows":
160        os.startfile(resolved)  # type: ignore[attr-defined]
161    else:
162        subprocess.run(["xdg-open", resolved], check=True)
163
164    return {
165        "opened": True,
166        "target": resolved,
167    }
168
169if __name__ == "__main__":
170    app.run(transport="stdio")

Bu kompakt bir sunucudur, ancak önemli olan uzunluğu değil, arayüzün şeklidir:

• her aracın çok net bir görevi vardır
• her araç yapılandırılmış veri döndürür
• komut yürütme kontrollüdür
• dosya erişimi köklüdür
• ekran görüntüleri bilinen bir klasöre gider

Yerel bir MCP sunucusunda tam olarak istediğiniz şey budur.

Bu araçlar neden bu şekilde tasarlandı?

Ajan araçları hakkındaki üst düzey içerik asla "işte kod" ile bitmemelidir. Araç şekli asıl derstir.

list_files

Bu araç, Claude'a güvenli bir keşif yüzeyi sağlar. Şu gibi soruları cevaplayabilmelidir:

• Bu proje klasöründe ne var?
• Belgeler'de hangi notlar var?
• İnceleyebileceğim bir günlük dosyası var mı?

Ancak özyinelemeli bir tam disk tarayıcısı haline gelmemelidir.

read_file

Bu genellikle tüm yerel araçların en kullanışlısıdır. Gerçek işin büyük bir kısmı hala yerel Markdown notlarında, günlüklerde, CSV'lerde, dokümanlarda ve proje dosyalarında gizlidir.

max_chars sınırı önemlidir. Büyük dosyalar bir bağlam ve gecikme sorunudur. Dev bir günlük dosyasının tüm içeriğini döndürmek nadiren kullanışlıdır.

run_command

Çoğu insanın dikkatsiz davrandığı yer burasıdır.

Güvenli model "kabuk erişimine izin ver, sonra en iyisini um" değildir. Güvenli model "küçük, kesin, incelenebilir bir komut setine izin ver"dir. Bu nedenle örnekte katı bir izin listesi kullanılmıştır.

take_screenshot

Bir ekran görüntüsü aracı değerlidir çünkü Claude'un masaüstü iş akışlarına katılmasını sağlar. İlk sürümünüz görüntüyü yalnızca diske kaydetse bile, bu raporlama, UI hata ayıklama, dokümantasyon yakalama ve yapılandırılmış devir teslimler için zaten kullanışlıdır.

open_target

Uygulama kontrolünün GUI otomasyonu ile başlaması gerekmez. Birçok iş akışı için "doğru klasörü, dosyayı veya URL'yi açmak" yeterlidir.

Bu, ilk günden itibaren tam imleç otomasyonuna ihtiyacınız varmış gibi davranmaktan daha dayanıklı bir v1'dir.

Sunucuyu Claude'a bağlama

Yerel MCP sunucuları genellikle stdio üzerinden çalıştırılır; bu, Claude'un süreci yerel olarak başlattığı ve onunla doğrudan stdin/stdout üzerinden iletişim kurduğu anlamına gelir. Yerel bir bilgisayar kontrol sunucusu için bu doğru varsayılandır çünkü gereksiz ağ maruziyetini önler 4 5.

Claude Desktop, yerel MCP sunucularını yapılandırma yoluyla destekler; burada sunucu sürecini sizin için başlatır. Pratikte, yorumlayıcı ve betik için mutlak yollar kullanmak en az kırılgan kurulumdur çünkü yerel GUI uygulama ortamları genellikle terminalinizden daha katıdır 2.

Minimum bir yapılandırma şöyle görünür:

1{
2  "mcpServers": {
3    "local-computer-control": {
4      "command": "/absolute/path/to/python",
5      "args": [
6        "/absolute/path/to/local-mcp-server/server.py"
7      ]
8    }
9  }
10}

uv'yi tercih ediyorsanız, bu da sorun değil:

1{
2  "mcpServers": {
3    "local-computer-control": {
4      "command": "/absolute/path/to/uv",
5      "args": [
6        "--directory",
7        "/absolute/path/to/local-mcp-server",
8        "run",
9        "python",
10        "server.py"
11      ]
12    }
13  }
14}

Yapılandırmayı kaydettikten ve Claude'u yeniden başlattıktan sonra, sunucu araçları yerel MCP araçları listesinde görünmelidir. Claude Desktop'un yerel MCP kurulumu tam olarak bu model etrafında inşa edilmiştir: yerel bir süreç başlatın, stdio üzerinden bağlanın ve araçları modele maruz bırakın 2 3.

Test için gerçekten kullanışlı olan komutlar

Sunucu bağlandıktan sonra karmaşık orkestrasyonla başlamayın. Doğrudan, sıkıcı kontrollerle başlayın.

Şu gibi komutları deneyin:

• "Masaüstü klasörümdeki dosyaları listele."
• "~/Documents/todo.md dosyasını oku ve ilk üç önceliği özetle."
• "Yerel proje klasörümde git status çalıştır ve neyin değiştiğini açıkla."
• "workspace-check adında bir ekran görüntüsü al."
• "Projemin README dosyasını aç."

Bu basit akışlar tutarlı bir şekilde çalışıyorsa, genişletmeye değer bir sunucunuz var demektir.

Çalışmıyorlarsa, daha fazla araç eklemek yalnızca gerçek sorunları gizleyecektir.

Yerel MCP sunucularının gerçekten değerli hale geldiği yerler

Bariz kullanım alanı geliştirmedir, ancak bu sadece bir kulvardır.

Geliştirici iş akışı

Claude şunları yapabilir:

• bir depo klasörünü inceleyin
• bir yapılandırma dosyasını okuyun
• git status çalıştırın
• bir hata durumunun ekran görüntüsünü alın
• proje dizinini açın

Bu, zaten çok fazla bağlam değiştirmeyi ortadan kaldırır.

Araştırma iş akışı

Claude şunları yapabilir:

• araştırma klasörlerini listeleyin
• Markdown notlarını açın ve özetleyin
• yapılandırılmış CSV'leri okuyun
• araçlardan veya panolardan ekran görüntüleri kaydedin
• kaynak dosyaları veya tarayıcı bağlantılarını açın

İçerik iş akışı

Claude şunları yapabilir:

• bir taslaklar klasörünü tarayın
• mevcut gönderi fikirlerini okuyun
• bir tasarım referansının ekran görüntüsünü alın
• doğru yazma dosyasını veya URL'yi açın
• bir yapı eseri veya taslak dışa aktarma oluşturan sınırlı bir komut çalıştırın

Operasyon iş akışı

Claude şunları yapabilir:

• onaylı dizinlerden günlükleri inceleyin
• salt okunur bir tanılama komutu çalıştırın
• ilgili klasörü veya pano bağlantısını açın
• bir kanıt ekran görüntüsü kaydedin

Mimarinin asıl amacı budur: bir gösteri olarak "bilgisayar kontrolü" değil, iş akışı sıkıştırması.

Güvenlik katmanı ürünün kendisidir

Bu, çok fazla teknik makalenin önemsediği bölümdür.

Yerel MCP'nin tehlikeli kısmı protokol değil, kötü izin tasarımıdır.

Bu sunucunun bir demonun ötesinde kullanılabilir olmasını istiyorsanız, güvenlik modelini erkenden oluşturun.

Dizin izin listelerini kullanın

Claude yalnızca açıkça onayladığınız yolları görebilmelidir. Bu nedenle _resolve_path(), dosya araçlarının çekirdeğidir.

Komut izin listelerini kullanın

İlk sürümde asla rastgele kabuk yürütmeyi açığa çıkarmayın. Satır satır denetleyebileceğiniz kesin komutlarla başlayın.

Okuma araçlarını eylem araçlarından ayırın

Salt okunur araçlar varsayılan olmalıdır. Eylem araçları kasıtlı olarak tanıtılmalıdır.

Her şeyi günlüğe kaydedin

Basit bir ekleme-amaçlı JSON günlüğü bile hata ayıklamayı ve güveni önemli ölçüde iyileştirir.

Yazma işlemleri için bir onay katmanı ekleyin

Daha sonra write_file, move_file veya delete_file eklerseniz, bu araçların ya ikinci bir onay belirteci gerektirmesini sağlayın ya da varsayılan olarak devre dışı bırakın.

Bir kuru-çalıştırma modu düşünün

Eylem gerçekleştiren araçlar için kuru-çalıştırma modu hafife alınır. Claude'un bir şey yapmadan önce ne yapacağını açıklamasını sağlar.

Mümkün olduğunda kısıtlı bir kullanıcı altında çalıştırın

Yerel otomasyon konusunda ciddiyseniz, MCP sunucunuza ihtiyacından fazla işletim sistemi ayrıcalığı vermeyin.

Yararlı bir temel kural:

• Seviye 1: salt okunur araçlar
• Seviye 2: dosya aç / uygulama aç gibi düşük riskli eylemler
• Seviye 3: onaylanmış yazma eylemleri
• Seviye 4: muhtemelen gelişigüzel açığa çıkarmamanız gereken yıkıcı eylemler

Çoğu insanın Seviye 4'e asla ihtiyacı olmaz.

v1'den sonra neyi geliştirmeli?

Sağlam bir ilk sürüm, daha yetenekli olma hakkını kazanır.

Temel sunucu kararlı hale geldikten sonraki mantıklı yükseltmeler şunlardır:

1. Merkezi politika dosyası

Kurallarınızı config/policy.json dosyasına taşıyın, böylece değişiklikler bildirimsel olur.

Örnek:

1{
2  "allowed_roots": [
3    "~/Documents",
4    "~/Desktop",
5    "./"
6  ],
7  "allowed_commands": [
8    "pwd",
9    "ls",
10    "git status",
11    "git diff --stat",
12    "python --version"
13  ]
14}

1. Yapılandırılmış günlük kaydı

Araç çağrılarını, zaman damgalarını, argümanları ve sonuçları logs/server.log veya bir JSONL dosyasına kaydedin.

1. Daha güvenli komut yürütme

Tek bir genel komut aracı yerine, komutları şunun gibi daha dar araçlara bölün:

• git_status
• show_current_directory
• list_project_files

Bu, Claude için araç seçimini ve sizin için güvenliği kolaylaştırır.

1. Daha iyi ekran görüntüsü yönetimi

"Ekran görüntüsünü diske kaydet"ten şuraya evrilebilirsiniz:

• zaman damgalı yakalamalar
• etkin pencere yakalama
• bölge yakalama
• dosya saklama kuralları

1. İşletim sistemine özel otomasyon bağdaştırıcıları

macOS'ta daha sonra AppleScript veya Kısayollar ekleyebilirsiniz. Windows'ta PowerShell veya UI Otomasyonu. Linux'ta masaüstüne özel başlatıcılar ve pencere araçları.

Ancak bu, sıkıcı yerel çekirdek güvenilir hale geldikten sonra gelmelidir.

İnsanların yerel MCP sunucularıyla yaptığı yaygın hatalar

Hatalar tahmin edilebilir.

Hata 1: Çok fazla güç, çok erken

İnsanlar tam bilgisayar kontrolü fikrini severler. Hata ayıklamaktan nefret ederler. Daha küçük başlayın.

Hata 2: Belirsiz araç adları

Araç adlarınız belirsizse, Claude onları kötü kullanacaktır. Açık olun.

Kötü:

• system_action
• computer_control

Daha iyi:

• list_files
• read_file
• run_command
• take_screenshot
• open_target

Hata 3: Yapılandırılmamış çıktılar

Karışık bir metin yığını, Claude'un temiz bir JSON nesnesine göre akıl yürütmesi daha zordur.

Hata 4: Günlük kaydı yok

Bir araç başarısız olursa ve nedenini göremezseniz, sistem tahmin oyununa dönüşür.

Hata 5: Modele kontrol katmanı gibi davranmak

Claude akıl yürütme katmanıdır. Sunucunuz yine de uygulama katmanı olmalıdır.

Bu ayrım tartışılmaz.

Bu mimari, düz otomasyondan daha iyi ne yapar?

Geleneksel masaüstü otomasyonu genellikle iki şeyden biridir:

• kırılgan GUI betiklemesi
• bir insanın tam olarak ne zaman çalıştıracağını bilmesini gerektiren izole betikler

Yerel bir MCP sunucusu bunu değiştirir çünkü Claude, kullanıcının talebine ve mevcut bağlama göre hangi aracı kullanacağına karar verebilir.

Bu, yalnızca bir komutu otomatikleştirmediğiniz anlamına gelir. Modelin üzerinde akıl yürütebileceği yerel bir yetenek katmanı oluşturuyorsunuz.

MCP'nin önemli hissettirmesinin nedeni budur. Bu sadece başka bir entegrasyon modeli değildir. Olası her iş akışını uygulama katmanında kodlamadan, araç kullanımını modele sunmanın daha temiz bir yoludur.

Saygı duymanız gereken sınırlar

İyi bir yerel MCP sunucusunun bile gerçek sınırlamaları vardır.

• Masaüstü otomasyonu işletim sistemleri arasında tutarsız olabilir.
• Ekran görüntüleri kullanışlıdır, ancak sihirli değildir.
• Uygulama başlatmak kolaydır; güvenilir UI manipülasyonu daha zordur.
• Genel kabuk erişimi tehlikelidir.
• Araç çıktıları çok büyükse bağlam şişkinliği gerçektir.
• Önemli olan her şey için insan onayı hala değerlidir.

Başka bir deyişle: "model eylem gerçekleştirebilir" ile "model gözetim olmadan hareket etmelidir"i karıştırmayın.

Daha değerli olan model, kör özerklik değil, işbirlikçi kontroldür.